diff --git a/docs/Developers/Guides/Chronicle Pull Oracles/GettingStarted.md b/docs/Developers/Guides/Chronicle Pull Oracles/GettingStarted.md
new file mode 100644
index 0000000..bc71e2e
--- /dev/null
+++ b/docs/Developers/Guides/Chronicle Pull Oracles/GettingStarted.md	
@@ -0,0 +1,42 @@
+---
+sidebar_position: 1
+description: Developer documentation for Chronicle's Pull Oracle
+keywords: [pull oracle]
+---
+# Getting Started
+
+Chronicle's pull oracles offer the absolute freshest pricing information on-demand. We provide an [NPM package](https://www.npmjs.com/package/@chronicleprotocol/pull-oracle) for simple integrations. Authentication is handled via tokens based on the [Ethereum Signed Messages](https://eips.ethereum.org/EIPS/eip-191) protocol.
+
+:::info
+Your public signing key must be allow-listed on our servers before your tokens will be accepted as valid.
+:::
+
+### Generating authentication tokens on the server:
+```js
+import { signAuthToken } from '@chronicleprotocol/pull-oracle';
+
+const { token, message } = await signAuthToken({
+  // private key is 0x prefixed 32 byte hex string
+  privateKey: "0xabc..."
+})
+```
+
+:::warning
+We highly recommend following best practices for private key generation and storage. Use a unique private key for creating auth tokens. DO NOT re-use this private key for any other purpose!
+:::
+
+Once the auth token is generated on the server, pass it to the client and register it with the `authenticate` method of the `pull-oracle` module for automatic inclusion in future requests.
+
+### Authenticating a user session on the client and fetching prices:
+```js
+import { authenticate, getPrices } from '@chronicleprotocol/pull-oracle';
+
+// token is received from the server
+// `authenticate` caches the token in memory so it only needs to be called once per session
+authenticate(token);
+
+const prices = await getPrices([
+  { wat: "MKR/USD", blockchain: "ETH" },
+  { wat: "ETH/USD", blockchain: "ETH" }
+]);
+```
diff --git a/docs/Developers/Guides/Chronicle Pull Oracles/Types.md b/docs/Developers/Guides/Chronicle Pull Oracles/Types.md
new file mode 100644
index 0000000..a6c142e
--- /dev/null
+++ b/docs/Developers/Guides/Chronicle Pull Oracles/Types.md	
@@ -0,0 +1,228 @@
+---
+sidebar_position: 6
+description: Pull Oracle - Types
+keywords: [pull oracle]
+---
+# Types & Constants
+
+## Types
+
+### `APIResponseError`
+
+Occurs when there is an error processing the request.
+
+```ts
+interface APIResponseError {
+  error: true;
+  data?: any;
+  message: string;
+  code: AuthTokenCode | APIErrorCode;
+}
+```
+
+---
+
+### `AuthTokenMessage`
+
+The message returned from [`signAuthToken`](./authenticate.md#signauthtoken).
+
+```ts
+type AuthTokenMessage {
+  description: string;
+  version: number;
+  validFrom: number;
+  validTo: number;
+  signer: Address;
+  nonce: number;
+}
+```
+
+- `description`: the description of the token, e.g. "Chronicle API token"
+- `version`: the authentication API version number
+- `validFrom`: unix epoch timestamp starting from then the token is valid, inclusive
+- `validTo`: unix epoch timestamp until when the auth token is valid, inclusive
+- `signer`: the address of the signer
+- `nonce`: unique number
+
+
+---
+
+### `Blockchain`
+
+A blockchain identifier of either the `shortName` or `chainId` per [chainid.network](https://chainid.network/chains.json).
+
+```ts
+type Blockchain = string | number;
+```
+
+---
+
+### `PairData`
+
+The data structure returned from [`getPairs`](./getPairs.md)
+
+```ts
+type PairData = {
+  scheme: Scheme;
+  blockchain: Blockchain;
+  pairs: Pairs;
+}
+```
+
+---
+
+### `Pairs`
+
+The data structure containing pairs.
+
+```ts
+type Pairs = Record<string, { bar: number; validators: Address[] }>;
+```
+
+Example:
+```ts
+{
+  "BTC/USD": {
+    bar: 13,
+    validators: [
+      "0xabc123...",
+      "0xabc123...",
+      "0xabc123...",
+      ...
+    ]
+  }
+}
+```
+
+---
+
+### `PriceData`
+
+The data structure returned from [`getPrices`](./getPrices.md)
+
+```ts
+type PriceData = {
+  wat: string;
+  scheme: Scheme;
+  bar: number;
+  messages: PriceMessage[];
+}
+```
+
+---
+
+### `PriceMessage`
+
+The data structure of an individual price message. A batch of price messages makes up a single oracle price.
+
+```ts
+type PriceMessage {
+  wat: string;
+  val: string;
+  age: number;
+  r: string;
+  s: string;
+  v: string;
+}
+```
+
+---
+
+### `PriceRequest`
+
+The data structure of the argument passed to [`getPrices`](./getPrices.md)
+
+```ts
+type PriceRequest {
+  wat: string;
+  scheme?: Scheme;
+}
+```
+
+---
+
+### `ValidatorData`
+
+The data structure returned from [`getPairs`](./getPairs.md)
+
+```ts
+type ValidatorData {
+  scheme: Scheme;
+  validators: Validator[];
+}
+```
+
+---
+
+## Constants
+
+:::info
+Note: all enum values are identical to their keys, but only keys are shown here for simplicity
+:::
+
+
+### `Scheme`
+
+Encryption scheme for price messages. Currently there is only one option, however more options may be offered in the future.
+
+```ts
+enum Scheme {
+  ECDSA
+}
+```
+- `ECDSA`: Price messages are signed with [Elliptic Curve Digital Signature Algorithm](https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm) encryption.
+
+---
+
+### `AuthTokenCodes`
+
+Response codes for auth token verification.
+
+```ts
+enum AuthTokenCode {
+  VALID,
+  EXPIRED,
+  NOT_YET_VALID,
+  DURATION_EXCEEDS_MAX,
+  INVALID_SIGNATURE,
+  INVALID_VERSION,
+  MALFORMED_TOKEN,
+  SIGNER_NOT_AUTHORIZED
+}
+```
+
+- `VALID`: Auth token is valid
+- `EXPIRED`: Auth token end time has passed
+- `NOT_YET_VALID`: Auth token start time has not yet occurred
+- `DURATION_EXCEEDS_MAX`: The period between auth token start and end times is too long
+- `INVALID_SIGNATURE`: The auth token `signer` field and recovered signature do not match
+- `INVALID_VERSION`: The auth token is using an unrecognized version
+- `MALFORMED_TOKEN`: The auth token has some other error not covered by the other codes
+- `SIGNER_NOT_AUTHORIZED`: The token signer is not authorized by Chronicle
+
+---
+
+### `APIErrorCode`
+
+Response codes for API errors.
+
+```ts
+enum APIErrorCode {
+  FAILED_REQUEST,
+  SCHEME_NOT_SUPPORTED,
+  BLOCKCHAIN_NOT_SUPPORTED,
+  PAIR_NOT_SUPPORTED,
+  MISSING_REQUIRED_PARAMETER,
+  METHOD_NOT_ALLOWED,
+  INVALID_REQUEST_DATA,
+}
+```
+
+- `FAILED_REQUEST`: The API request failed to receive a valid response from the server
+- `SCHEME_NOT_SUPPORTED`: The API request was made for a [Scheme](#scheme) that is not supported
+- `BLOCKCHAIN_NOT_SUPPORTED`: The API request was made for a [Blockchain](#blockchain) that is not supported
+- `PAIR_NOT_SUPPORTED`: The API request was made for a [Pair](#pair) that is not supported
+- `MISSING_REQUIRED_PARAMETER`: The API request was missing a required parameter and was therefore unable to complete
+- `METHOD_NOT_ALLOWED`: The HTTP method used to access the API is not allowed
+- `INVALID_REQUEST_DATA`: The request data was not parseable or inadequate to complete the request
+
diff --git a/docs/Developers/Guides/Chronicle Pull Oracles/authenticate.md b/docs/Developers/Guides/Chronicle Pull Oracles/authenticate.md
new file mode 100644
index 0000000..8e3879c
--- /dev/null
+++ b/docs/Developers/Guides/Chronicle Pull Oracles/authenticate.md	
@@ -0,0 +1,91 @@
+---
+sidebar_position: 2
+description: Pull Oracle - authenticate
+keywords: [pull oracle]
+---
+
+# Authentication
+
+## `signAuthToken`
+
+A server-side function which creates an auth token to be used to [authenticate](#authenticate) [getPrices](./getPrices.md) requests.
+
+### Usage
+
+Generating authentication tokens on the server:
+```js
+import { signAuthToken } from '@chronicleprotocol/pull-oracle';
+
+const { token, message } = await signAuthToken({
+  // private key is 0x prefixed 32 byte hex string
+  privateKey: "0xabc..."
+})
+```
+
+### Returns
+
+```js
+{ 
+  token: "...", 
+  message: AuthTokenMessage 
+}
+```
+
+### Parameters
+
+```ts
+{ privateKey: "0xabc...", duration: 1800 }
+```
+
+#### `privateKey`
+
+- Type: `string`
+
+The `privateKey` for the account signing the auth token.
+
+#### `duration`
+
+- _Optional_
+- Default: 1800
+- Type: `number`
+
+The duration of validity for the auth token in seconds.
+
+---
+
+## `authenticate`
+
+A client-side function which validates and caches the auth token which was received from the server for future use with [getPrices](./getPrices.md).
+
+### Usage
+
+```js
+import { authenticate } from '@chronicleprotocol/pull-oracle';
+
+// token is received from the server
+// `authenticate` caches the token in memory so it only needs to be called once per session
+authenticate(token);
+```
+
+### Returns
+
+- `boolean`: whether the provided auth token is _currently_ valid.
+
+---
+
+# `isAuthenticated`
+
+A function to check whether the library has a currently valid auth token previously cached by the [authenticate](#authenticate) function.
+
+### Usage
+
+```js
+import { isAuthenticated } from '@chronicleprotocol/pull-oracle';
+
+// token from the cache is verified
+const isAuthenticated = isAuthenticated()
+```
+
+### Returns
+
+- `boolean`: whether the cached auth token is _currently_ valid.
\ No newline at end of file
diff --git a/docs/Developers/Guides/Chronicle Pull Oracles/getPairs.md b/docs/Developers/Guides/Chronicle Pull Oracles/getPairs.md
new file mode 100644
index 0000000..8e259a1
--- /dev/null
+++ b/docs/Developers/Guides/Chronicle Pull Oracles/getPairs.md	
@@ -0,0 +1,100 @@
+---
+sidebar_position: 4
+description: Pull Oracle - getPairs
+keywords: [pull oracle]
+---
+
+# Getting Pairs
+
+## `getPairs`
+
+Returns the pairs supported on a given [`Blockchain`](./Types.md#blockchain), and optionally with a given [`Scheme`](./Types.md#scheme).
+
+### Usage
+
+```ts
+import { getPairs } from '@chronicleprotocol/pull-oracle';
+
+const pairs = await getPairs({ blockchain });
+```
+
+---
+
+### Returns
+
+Returns a promise that provides the [`Blockchain`](./Types.md#blockchain), [`Scheme`](./Types.md#scheme), and a [`Pairs`](./Types.md#pairs) object.
+
+```ts
+interface PairData {
+  blockchain: Blockchain,
+  scheme: Scheme,
+  pairs: {
+    [pair: string]: {
+      bar: number,
+      validators: Address[]
+    },
+    ...
+  }
+}
+```
+
+#### Example
+
+```ts
+{
+  blockchain: "ETH",
+  scheme: "ECDSA",
+  pairs: {
+    "BTC/USD": {
+      bar: 13,
+      validators: [
+        "0xabc123...",
+        "0xabc123...",
+        "0xabc123...",
+        ...
+      ]
+    },
+    "ETH/USD": {
+      bar: 13,
+      validators: [
+        "0xabc123...",
+        "0xabc123...",
+        "0xabc123...",
+        ...
+      ]
+    },
+    ...
+  }
+}
+```
+
+### Parameters
+
+#### `blockchain`
+- Type: [`Blockchain`](./Types.md#blockchain)
+
+A blockhain identifier indicating on which chain the pairs are going to be used.
+
+#### `scheme`
+- _Optional_
+- Type: [`Scheme`](./Types.md#scheme)
+- Default: `ECDSA`
+
+The encryption scheme used for price messages of these pairs
+
+### Errors
+
+In the event of an error, the return object will be an [`APIResponseError`](./Types.md#apiresponseerror).
+
+#### Example
+```ts
+{
+  error: true,
+  message: `VADER blockchain not supported`,
+  data: {
+    scheme: "ECDSA",
+    blockchain: "VADER"
+  },
+  code: APIErrorCode.BLOCKCHAIN_NOT_SUPPORTED
+}
+```
diff --git a/docs/Developers/Guides/Chronicle Pull Oracles/getPrices.md b/docs/Developers/Guides/Chronicle Pull Oracles/getPrices.md
new file mode 100644
index 0000000..6fa0de3
--- /dev/null
+++ b/docs/Developers/Guides/Chronicle Pull Oracles/getPrices.md	
@@ -0,0 +1,98 @@
+---
+sidebar_position: 3
+description: Pull Oracle - getPrices
+keywords: [pull oracle]
+---
+
+# Getting Prices
+
+## `getPrices`
+
+Fetches the latest price messages for one or more pairs on a given blockchain.
+
+### Usage
+
+:::info
+`getPrices` requires that you [authenticate](./authenticate.md#authenticate) with a valid auth token first
+:::
+
+```ts
+import { getPrices } from '@chronicleprotocol/pull-oracle';
+
+const prices = await getPrices([
+  { wat: "MKR/USD", blockchain: "ETH" },
+  { wat: "ETH/USD", blockchain: "ETH" }
+]);
+```
+
+### Returns
+
+Returns a promise that provides an array of objects corresponding to the input array of [`wats`](#wats).
+
+```ts
+[
+  {
+    wat: string,
+    scheme: Scheme,
+    blockchain: Blockchain,
+    bar: number,
+    messages: [
+      {
+        wat: string,
+        val: string,
+        age: number,
+        r: string,
+        s: string,
+        v: string,
+        validator: Address
+      }
+    ],
+    callData: Hex
+  }
+]
+```
+
+### Parameters
+
+#### `wats`
+- Type: `array`
+
+The list of pairs to fetch.
+
+```ts
+[{ wat: "ETH/USD", blockchain: "ETH" }, ...]
+```
+
+#### `wat`
+- Type: `string`
+
+A valid [pair](./getPairs.md).
+
+#### `blockchain`
+- Type: [`Blockchain`](./Types.md#blockchain)
+
+A blockhain identifier indicating on which chain the messages are going to be verified.
+
+#### `scheme`
+- _Optional_
+- Default: `ECDSA`
+- Type: [`Scheme`](./Types.md#scheme)
+
+The encryption scheme used for price messages
+
+### Errors
+
+In the event of an error, the return object will be provided with `error: true` and an [error code](./Types.md#authtokencode).
+
+```ts
+{
+  error: true,
+  message: "Invalid authorization token: EXPIRED",
+  data: {
+    wat: "ETH/USD",
+    scheme: "ECDSA",
+    blockchain: "ETH"
+  },
+  code: "EXPIRED"
+}
+```
diff --git a/docs/Developers/Guides/Chronicle Pull Oracles/getValidators.md b/docs/Developers/Guides/Chronicle Pull Oracles/getValidators.md
new file mode 100644
index 0000000..85fadfd
--- /dev/null
+++ b/docs/Developers/Guides/Chronicle Pull Oracles/getValidators.md	
@@ -0,0 +1,79 @@
+---
+sidebar_position: 5
+description: Pull Oracle - getValidators
+keywords: [pull oracle]
+---
+
+# Getting Validators
+
+## `getValidators`
+
+Returns the validators supported on a given [`Blockchain`](./Types.md#blockchain), and optionally with a given [`Scheme`](./Types.md#scheme).
+
+### Usage
+
+```ts
+import { getValidators } from '@chronicleprotocol/pull-oracle';
+
+const validators = await getValidators({ blockchain });
+```
+
+---
+
+### Returns
+
+Returns a promise that provides the [`Blockchain`](./Types.md#blockchain), [`Scheme`](./Types.md#scheme), and a [`Validators`](./Types.md#validators) array of addresses.
+
+```ts
+interface ValidatorData {
+  blockchain: Blockchain;
+  scheme: Scheme;
+  validators: Address[];
+}
+```
+
+#### Example
+
+```ts
+{
+  blockchain: "ETH",
+  scheme: "ECDSA",
+  validators: [
+    "0xabc123...",
+    "0xabc123...",
+    "0xabc123...",
+    ...
+  ]
+}
+```
+
+### Parameters
+
+#### `blockchain`
+- Type: [`Blockchain`](./Types.md#blockchain)
+
+A blockhain identifier indicating on which chain the validators are going to be used.
+
+#### `scheme`
+- _Optional_
+- Type: [`Scheme`](./Types.md#scheme)
+- Default: `ECDSA`
+
+The encryption scheme used for price messages of these validators
+
+### Errors
+
+In the event of an error, the return object will be an [`APIResponseError`](./Types.md#apiresponseerror).
+
+#### Example
+```ts
+{
+  error: true,
+  message: `VADER blockchain not supported`,
+  data: {
+    scheme: "ECDSA",
+    blockchain: "VADER"
+  },
+  code: APIErrorCode.BLOCKCHAIN_NOT_SUPPORTED
+}
+```