> For the complete documentation index, see [llms.txt](https://docs.v2.pod.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.v2.pod.network/guides-references/guides/read-market-data.md).

# Read market data

Pod's full node includes a built-in indexer and serves its market data two ways, on the same host as the JSON-RPC endpoint:

* **REST** under `/v1` for one-shot reads: markets, books, candles, solutions, and an account's orders and fills. See the [REST reference](https://docs.v2.pod.network/guides-references/references/rest.md) for every route.
* **WebSocket subscriptions** (`eth_subscribe`) that push what changed after every auction tick.

For every stream, seed over REST, then subscribe with `since` set to the solution time (µs) the REST response was current at. On delta channels the node replays every tick after that point, then streams live, with no gap or duplicate. On state channels (`pod_markets`, `pod_positions`, `pod_triggers`) the node waits until its state reaches `since`, sends one snapshot, then streams live.

```javascript
const REST = "https://staging-rpc.podtestnet.dev/v1";
const orderbookId = "0x0000000000000000000000000000000000000000000000000000000000000001"; // NVDAx-USD spot
const get = async (path) => {
  const res = await fetch(`${REST}${path}`);
  if (!res.ok) throw new Error(`${path}: ${res.status} ${await res.text()}`);
  return res.json();
};
```

Amounts are 1e18-scaled, in two encodings. `/clob/markets`, `/clob/markets/stats` and `/clob/backstop-transfers` use decimal strings. Candles, orders, fills, solutions, positions and balances encode unsigned prices and amounts as `0x` hex strings, and signed values as decimal strings. Orderbook snapshots key their price levels by decimal strings and give each level's volume in hex. Timestamps ending in `_us` are microseconds.

## Markets

```javascript
// Static configuration: name, tokens, fees, tick precision, lot size, status, ...
const markets = await get("/clob/markets");

// Live 24h statistics, plus the solution time they are current at.
const { solution_now, markets: stats } = await get("/clob/markets/stats");
// stats: [{ orderbook_id, last_clearing_price, volume_24h, high_24h, low_24h, mark_price, ... }]
```

Optional stats fields (`last_clearing_price`, `high_24h`, the perp fields, ...) are omitted until the market has the data.

## Orderbook

```javascript
const book = await get(`/clob/orderbook/${orderbookId}?depth=20`);
// { orderbook_id, buys: { "<price>": { volume } }, sells: { ... },
//   buys_count, sells_count, clearing_price, timestamp, ... }
```

`depth` keeps the best N price levels per side (minimum 1; omit it for the whole book). Both sides are keyed by price in ascending order: the best bid is the last key of `buys`, the best ask the first key of `sells`. `buys_count`/`sells_count` count the full book even when truncated. `timestamp` is the deadline (µs) of the batch the snapshot was taken after. The route answers 404 until a batch has cleared that orderbook since the node started.

## Candles

```javascript
const nowSecs = Math.floor(Date.now() / 1000);
const { candles, range, solution_now_us } = await get(
  `/clob/candles/${orderbookId}?resolution=1m&from=${nowSecs - 3600}&to=${nowSecs}`
);
// candles: [{ timestamp, open, high, low, close, volume, quote_volume }], newest first

// Start of the bucket still forming at solution time; build it from pod_candles.
const bucketUs = 60_000_000; // 1m
const formingStartUs = Math.floor(solution_now_us / bucketUs) * bucketUs;
```

`resolution` is one of `1m`, `5m`, `15m`, `30m`, `1h`, `4h`, `1d`, `1w`, `1M`. `from`/`to` are seconds and select `[from, to)`; `limit` caps the page at up to 500 candles. Only closed bars are returned. To page further back, request again with `to = range.from_us / 1e6`.

Build the forming bar, including the trades it already holds, from `pod_candles` ticks. Subscribe with `since: formingStartUs - 1`: `since` replays every tick strictly after it, so the whole forming bucket arrives before live ticks. The node keeps 16,384 ticks for replay (about 2.3 hours at the 500 ms cadence), enough for a forming bucket of up to 1h. For `4h` and coarser, first fill the forming bar from closed `1h` candles over `[formingStartUs, start of the current hour)`, then replay ticks from the start of the current hour.

## Solutions

```javascript
const { solutions } = await get(`/clob/solutions?orderbook=${orderbookId}&limit=50`);
// [{ orderbook_id, timestamp, clearing_price, mark_price, volume, oracle_price, funding_rate, ... }]
```

One row per orderbook per auction tick, newest first. `limit` counts ticks (1 to 200); page back with `until_us` (exclusive) set to the oldest `timestamp` you hold, or bound the window from below with `since_us` (inclusive).

## Account orders and fills

```javascript
const page = await get(`/clob/orders/${walletAddress}?limit=50`);
// { orders: [...], next_cursor, total_count, solution_now }
// next page: get(`/clob/orders/${walletAddress}?limit=50&cursor=${page.next_cursor}`)

const { fills } = await get(`/clob/fills/${walletAddress}?orderbook=${orderbookId}&from_us=${Date.now() * 1000 - 3600e6}`);
// [{ orderbook_id, order_id, price, base_amount, quote_amount, fee, timestamp, ... }]
```

Orders come newest first; `next_cursor` is `null` on the last page. Fills take `from_us`/`to_us` (`to_us` defaults to now) and up to 500 rows.

## Stream live updates

Open one WebSocket to the RPC host and subscribe once per stream. Each subscription confirms with an id; updates then arrive as `eth_subscription` notifications carrying that id.

```javascript
const ws = new WebSocket("wss://staging-rpc.podtestnet.dev");
const handlers = new Map(); // request id -> handler, then subscription id -> handler
let nextId = 1;

function subscribe(channel, params, onUpdate) {
  const id = nextId++;
  handlers.set(id, onUpdate);
  ws.send(JSON.stringify({ jsonrpc: "2.0", id, method: "eth_subscribe", params: [channel, params] }));
}

ws.onmessage = ({ data }) => {
  const msg = JSON.parse(data);
  if (msg.id !== undefined) {
    if (msg.error) throw new Error(`subscribe failed: ${msg.error.message}`);
    handlers.set(msg.result, handlers.get(msg.id)); // subscription confirmed
    handlers.delete(msg.id);
  } else if (msg.method === "eth_subscription") {
    const { subscription, result, error } = msg.params;
    if (error) return console.warn("subscription closed", error); // resubscribe with error.data.resume_since
    handlers.get(subscription)?.(result);
  }
};

ws.onopen = () => {
  const ids = [orderbookId];
  // Delta channels: replay every tick after `since`, then live. Use the
  // solution-time watermark (`solution_now`) as `since`; it stays inside the
  // replay buffer even for a quiet book.
  subscribe("pod_orderbook", { orderbook_ids: ids, depth: 20, since: solution_now }, (snapshot) => {});
  subscribe("pod_candles", { orderbook_ids: ids, since: formingStartUs - 1 }, (tick) => {
    // { orderbook, timestamp_us, price, volume }: fold into the forming bar
  });
  subscribe("pod_orders_v2", { bidder: walletAddress, since: page.solution_now }, (frame) => {
    // one frame per orderbook per batch: orders created in it, plus events (fills, cancels, ...)
  });
  // State channel: with `since`, waits until the node reaches it, sends every subscribed market's current entry, then one
  // entry per market cleared (or changing status) in each tick.
  subscribe("pod_markets", { orderbook_ids: ids, since: solution_now }, (entry) => {});
};
```

* `pod_orderbook` pushes a full snapshot (the REST shape) for each subscribed book cleared in a tick.
* `pod_candles` pushes one clearing-price tick per cleared book.
* `pod_orders_v2` streams order activity; `bidder` narrows it to one account and `bidders` to up to 64. See the `eth_subscribe` entry in the [JSON-RPC reference](https://docs.v2.pod.network/guides-references/references/json-rpc.md) for the frame format.
* `pod_markets` pushes the `/clob/markets/stats` entry plus the market's lifecycle (`status`, and `live_at_us`, `disable_at_us`, `settlement_price` once set).

If `since` is older than the node's replay buffer, the subscribe call fails with `-32602` `since too old`: seed again over REST and resubscribe with the new watermark. A subscription the server ends itself (a slow consumer, a node shutdown) arrives as a notification carrying `error`; see [JSON-RPC Errors](https://docs.v2.pod.network/guides-references/references/json-rpc-errors.md#subscription-close-notifications) for how to resume.

## Reading through several nodes

Account reads and pushes carry `timestamp`: the deadline of the last executed tick on the answering node, in microseconds. This covers `ob_getPositions`, `ob_getTriggers`, `GET /v1/clob/positions|balances|triggers/{account}`, and the `pod_positions` and `pod_triggers` pushes; `pod_markets` pushes and the `ob_getOrders`, `ob_getFills`, `ob_getSolutions`, `ob_getBackstopTransfers` and `ob_getMarkets` responses carry the indexer watermark under the same name. Ticks execute in lockstep on every node, so the value is comparable across nodes. Behind a load balancer a lagging node can answer after a leading one, so pass the highest `timestamp` you hold as the minimum, as below. Two requests for the same account or orderbook in flight at once (a REST poll and a push) can still land in either order: keep the highest `timestamp` seen and drop any response or push below it. On equal values, keep the later one.

To get an answer at least as fresh as one you already hold, pass the highest `timestamp` you hold as the `timestamp` query parameter (REST) or trailing parameter (`ob_getPositions`, `ob_getTriggers`, `ob_getOrderbook`, `ob_getOrders`, `ob_getFills`, `ob_getSolutions`, `ob_getBackstopTransfers`, `ob_getMarkets`), or as `since` when subscribing to `pod_positions`, `pod_triggers` or `pod_markets`. The node waits until the state behind the read reaches it; a value later than the node's clock plus the wait is rejected without waiting. If it cannot within its wait, REST answers HTTP 503 with `Retry-After: 1` and `{"timestamp": <node's current value>}`, and JSON-RPC (including `eth_subscribe`) returns error `995`; retry after `Retry-After`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.v2.pod.network/guides-references/guides/read-market-data.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
