> 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/references/rest.md). # REST API Pod full nodes serve a read-only REST API under `/v1` on the JSON-RPC port. The base URL is the RPC URL plus `/v1`; for the testnet, `https://rpc.podtestnet.dev/v1`. All routes are `GET` and allow any origin (CORS). * Markets, Account and Explorer routes (`/v1/clob/*`, `/v1/tx/{hash}`, `/v1/transactions`) require a node running the CLOB indexer. * Bridge routes (`/v1/bridge/*`) are served by every node. Errors are plain text: `400` for a malformed path or query parameter, `404` where a route says so, and `503` (`clob indexer unavailable`) when the indexer or execution engine could not answer. Bridge routes answer a failed read with an empty `500`. *** ### Caching Responses carry a `Cache-Control` header: | Header | Routes | | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `public, max-age=31536000, immutable` | `candles` once every bucket of the requested window has closed; `orders` and `activity` once the page's upper bound has been reached by solution time and every order on it is terminal. | | `public, max-age=60` | `markets`. | | `no-store` | Everything else under `/v1/clob`, `/v1/tx` and `/v1/transactions`, and the cases above that are not yet final. | Bridge routes set no `Cache-Control` header. To get a cacheable page, bound it in the past: pass `to` on `candles` and `activity`, and `until` or a `cursor` on `orders`. ### Encodings | Value | Encoding | | ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Addresses, hashes, orderbook ids | `0x` hex. Orderbook ids are always the full 32 bytes. | | Timestamps | Microseconds, as JSON numbers — except order and trigger `deadline`, which is a decimal string. | | Unsigned amounts and prices (1e18) | `0x` hex on `candles`, `orderbook` (price-level keys are decimal strings), `solutions`, `orders`, `fills`, `positions`, `balances`, `triggers`, the `order` entries of `activity`, and the bridge routes. | | Signed amounts (sizes, PnL, funding) | Decimal strings everywhere. | | `markets`, `markets/stats`, `backstop-transfers`, non-order `activity` entries | Every amount and price is a decimal string. | | Bridge `proof`, `aux_tx_suffix` | JSON arrays of byte values. | Query parameters follow their route: `candles` `from`/`to` and `orders` `until` are unix seconds; every other time parameter is microseconds. ### REST then websocket REST seeds state; the [websocket subscriptions](/guides-references/references/json-rpc.md) keep it current. Seed responses carry `solution_now` (`solution_now_us` on `candles`), the newest batch deadline they reflect. Subscribe with `since` set to that value. Delta channels replay every tick after it; state channels (`pod_markets`, `pod_positions`, `pod_triggers`) send one current snapshot. If the channel rejects `since` as too old, seed from REST again. | Seed from | Then subscribe to | | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/v1/clob/orders/{account}` | `pod_orders_v2` | | `/v1/clob/activity/{account}` | `pod_activity` | | `/v1/clob/candles/{orderbook}` | `pod_candles` (`since` is the forming bucket's start − 1µs, so its earlier trades replay; replay holds 16,384 ticks, about 2.3h, so above `1h` seed the forming bar from closed `1h` candles first) | | `/v1/clob/markets/stats` | `pod_markets` | | `/v1/bridge/withdrawals/{account}` | `pod_withdrawals` (`since` is the last `timestamp_us`) | --- # 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/references/rest.md?ask=&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.