diff --git a/README.md b/README.md
index ff68231..7ea40c0 100644
--- a/README.md
+++ b/README.md
@@ -7,7 +7,7 @@
 
 Being promise-based, you can await the result of your function inline
 
-### Usage
+### Getting started
 
 **Importing**
 
@@ -56,3 +56,38 @@ console.log(myThunk.isResolving()) // true
 console.log(myThunk.isResolved()) // false
 console.log(myThunk.isRejected()) // false
 ```
+
+**Cache auto-refresh**
+
+Setting a ttl (time-to-live) will allow your function to automatically be re-invoked if the value is considered stale. Great for caching access tokens, or any values that can be time-expensive to refresh on every operation.
+
+```js
+let counter = 0
+
+const getNextCounter = async () => {
+  counter += 1
+  return counter
+}
+
+const counterCache = new Phunk(getNextCounter, { ttl: 1000 })
+
+console.log(await counterCache.current()) // 1
+// wait at least 1 second
+console.log(await counterCache.current()) // 2
+```
+
+### Configuration
+
+Optionally pass a configuration object as a second argument to the constructor, with the following options
+
+* `init`: Optional, defaults to `false`, set to `true` to immediately invoke your function and have the result ready for when you first call `.current()`.
+* `cacheRejections`: Optional, defaults to `false`, set to `true` for your Phunky instance to cache any errors that are thrown by your function. If `false`, calling `.current()` will try re-invoking your function if it previously rejected.
+* `ttl`: (time-to-live) Optional. If set, it must be a positive integer for the number of **milliseconds** resolved values should live for. Any calls to `.current()` after that time, will automatically re-invoke your function to get an updated value.
+
+### Class methods
+
+* `current()`: Returns a promise of the result of the previous invocation of your function, or will await the result of the next invocation of your function if it has not previously been invoked or other criteria are met, see `cacheRejections` and `ttl` config options.
+* `next()`: Returns a promise of the result of the next invocation of your function.
+* `isResolving()`: Returns a boolean of whether your function is currently being invoked.
+* `isResolved()`: Returns a boolean of whether your function previously resolved without error. Will always return `false` if `isResolving()` returns `true`.
+* `isRejected()`: Returns a boolean of whether your function previously rejected with an error. Will always return `false` if `isResolving()` returns `true`.