> ## Documentation Index
> Fetch the complete documentation index at: https://pmxt.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Fetch Order Book
> Fetch the order book (bids/asks) for a specific outcome. Supports live and historical queries. For historical data, pass `since` to get a single snapshot, or `since` + `until` to get an array of fully reconstructed L2 books from the archive. Range queries return up to `limit` snapshots (default 100, max 1000).
## Use cases
### Live order book
Fetch the current L2 order book for an outcome from the exchange's live order book endpoint. For Polymarket this is a live CLOB call: pass the outcome token ID directly and omit historical params.
`poly.fetch_order_book(token_id)` without `params.since` or `params.until` is live-only. It does not read PMXT Archive data and may fail for closed, resolved, or otherwise inactive Polymarket markets with an error such as `No orderbook exists`.
```python Python theme={null}
import pmxt
poly = pmxt.Polymarket(pmxt_api_key="pmxt_...")
book = poly.fetch_order_book("104932610032177696635191871147557737718087870958469629338467406422339967452218")
print(f"{len(book.bids)} bids, {len(book.asks)} asks")
```
```javascript JavaScript theme={null}
import { Polymarket } from "pmxtjs";
const poly = new Polymarket({ pmxtApiKey: "pmxt_..." });
const book = await poly.fetchOrderBook("104932610032177696635191871147557737718087870958469629338467406422339967452218");
console.log(`${book.bids.length} bids, ${book.asks.length} asks`);
```
```bash curl theme={null}
curl "https://api.pmxt.dev/api/polymarket/fetchOrderBook?outcomeId=104932610032177696635191871147557737718087870958469629338467406422339967452218" \
-H "Authorization: Bearer ***"
```
### Historical snapshot
Get the order book at a specific point in time by passing `since` as a Unix timestamp in milliseconds. Historical Polymarket queries are served from the PMXT Archive and return the nearest reconstructed snapshot at or before that time.
For binary markets, you can pass the Polymarket condition ID as the first argument and choose the side with `params.outcome`. Use `"yes"` or `"no"` instead of copying the long outcome token ID.
```python Python theme={null}
import pmxt
poly = pmxt.Polymarket(pmxt_api_key="pmxt_...")
# Historical lookup against PMXT Archive, not the live CLOB.
book = poly.fetch_order_book(
"0xc704f74e2f9dfae70f770cb253ffadde10768eeab41233098bf5ac67995a94b5",
params={"since": 1779487200000, "outcome": "yes"},
)
print(f"{book.dt}: {len(book.bids)} bids, {len(book.asks)} asks")
print(f" best bid: {max(b.price for b in book.bids):.3f}")
print(f" best ask: {min(a.price for a in book.asks):.3f}")
```
```javascript JavaScript theme={null}
import { Polymarket } from "pmxtjs";
const poly = new Polymarket({ pmxtApiKey: "pmxt_..." });
// Historical lookup against PMXT Archive, not the live CLOB.
const book = await poly.fetchOrderBook(
"0xc704f74e2f9dfae70f770cb253ffadde10768eeab41233098bf5ac67995a94b5",
undefined,
{ since: 1779487200000, outcome: "yes" }
);
console.log(`${book.datetime}: ${book.bids.length} bids, ${book.asks.length} asks`);
console.log(` best bid: ${Math.max(...book.bids.map((b) => b.price)).toFixed(3)}`);
console.log(` best ask: ${Math.min(...book.asks.map((a) => a.price)).toFixed(3)}`);
```
```bash curl theme={null}
curl -X POST "https://api.pmxt.dev/api/polymarket/fetchOrderBook" \
-H "Authorization: Bearer ***" \
-H "Content-Type: application/json" \
-d '{"args":["0xc704f74e2f9dfae70f770cb253ffadde10768eeab41233098bf5ac67995a94b5", null, {"since": 1779487200000, "outcome": "yes"}]}'
```
### Historical crypto 5m events
Polymarket crypto 5-minute slugs such as `btc-updown-5m-1779481500` are event slugs. Use `fetch_event(slug=...)`, then select the nested market you want. Do not use `fetch_market(slug=...)` for these event-level slugs.
```python Python theme={null}
import pmxt
poly = pmxt.Polymarket(pmxt_api_key="pmxt_...")
event = poly.fetch_event(slug="btc-updown-5m-1779481500")
market = event.markets[0]
book = poly.fetch_order_book(
market.market_id,
params={"since": 1779487200000, "outcome": "yes"},
)
print(f"{market.title}: {book.dt}")
```
```javascript JavaScript theme={null}
import { Polymarket } from "pmxtjs";
const poly = new Polymarket({ pmxtApiKey: "pmxt_..." });
const event = await poly.fetchEvent({ slug: "btc-updown-5m-1779481500" });
const market = event.markets[0];
const book = await poly.fetchOrderBook(
market.marketId,
undefined,
{ since: 1779487200000, outcome: "yes" }
);
console.log(`${market.title}: ${book.datetime}`);
```
```bash curl theme={null}
curl -X POST "https://api.pmxt.dev/api/polymarket/fetchEvent" \
-H "Authorization: Bearer ***" \
-H "Content-Type: application/json" \
-d '{"kwargs":{"slug":"btc-updown-5m-1779481500"}}'
```
### Historical range (reconstructed L2 books)
Pass both `since` and `until` to get an array of fully reconstructed L2 order book snapshots. Each snapshot is a complete book at that moment in time — not deltas.
The API returns up to `limit` snapshots from the PMXT Archive. Defaults to 100 snapshots per request, max 1000. For raw bulk downloads, use the Parquet files in the [PMXT Archive](https://archive.pmxt.dev) instead of trying to stream bulk data through the live order book endpoint.
```python Python theme={null}
import pmxt
poly = pmxt.Polymarket(pmxt_api_key="pmxt_...")
event = poly.fetch_event(slug="btc-updown-5m-1779481500")
market = event.markets[0]
books = poly.fetch_order_book(
market.market_id,
params={
"since": 1779480000000,
"until": 1779487200000,
"outcome": "yes",
"limit": 100,
}
)
print(f"{len(books)} snapshots")
for ob in books[:3]:
print(f" {ob.dt} bid={ob.bids[0].price} ask={ob.asks[0].price}")
```
```javascript JavaScript theme={null}
import { Polymarket } from "pmxtjs";
const poly = new Polymarket({ pmxtApiKey: "pmxt_..." });
const event = await poly.fetchEvent({ slug: "btc-updown-5m-1779481500" });
const market = event.markets[0];
const books = await poly.fetchOrderBook(
market.marketId,
undefined,
{ since: 1779480000000, until: 1779487200000, outcome: "yes", limit: 100 }
);
console.log(`${books.length} snapshots`);
books.slice(0, 3).forEach((ob) =>
console.log(` ${ob.datetime} bid=${ob.bids[0].price} ask=${ob.asks[0].price}`)
);
```
```bash curl theme={null}
curl -X POST "https://api.pmxt.dev/api/polymarket/fetchOrderBook" \
-H "Authorization: Bearer ***" \
-H "Content-Type: application/json" \
-d '{"args":["0xc704f74e2f9dfae70f770cb253ffadde10768eeab41233098bf5ac67995a94b5", null, {"since": 1779480000000, "until": 1779487200000, "outcome": "yes", "limit": 100}]}'
```
Historical order book data is backed by the [PMXT Archive](https://archive.pmxt.dev) — the same tick-level data available as Parquet files, but queryable directly from the API without downloading or parsing files. Historical `fetchOrderBook` supports Polymarket, Kalshi, Limitless, and Opinion.
## OpenAPI
````yaml GET /api/{exchange}/fetchOrderBook
openapi: 3.0.0
info:
title: PMXT Hosted API
description: >-
One API for supported prediction markets. Hosted catalog search in under
10ms, a unified schema for supported venues, and venue-native trading where
venues expose writes.
version: 2.54.0
servers:
- url: https://api.pmxt.dev
description: Hosted PMXT (production)
security: []
tags:
- name: Hosted
description: >-
Requires a PMXT API key. These endpoints use the cross-venue catalog and
have no local equivalent.
- name: Local Only
description: >-
Executed locally by the SDK against the venue. Never proxied through PMXT
servers.
- name: Data Feeds
description: >-
Auxiliary price and oracle data feeds (Binance, Chainlink).
CCXT-compatible method names and response shapes.
paths:
/api/{exchange}/fetchOrderBook:
get:
summary: Fetch Order Book
description: >-
Fetch the order book (bids/asks) for a specific outcome. Supports live
and historical queries. For historical data, pass `since` to get a
single snapshot, or `since` + `until` to get an array of fully
reconstructed L2 books from the archive. Range queries return up to
`limit` snapshots (default 100, max 1000).
operationId: fetchOrderBook
parameters:
- $ref: '#/components/parameters/ExchangeParam'
- in: query
name: outcomeId
required: true
schema:
type: string
- in: query
name: limit
required: false
schema:
type: number
- in: query
name: side
required: false
schema:
type: string
enum:
- 'yes'
- 'no'
description: >-
Outcome side: 'yes' or 'no'. Required for exchanges like Limitless
where the API returns a single orderbook per market.
- in: query
name: outcome
required: false
schema:
type: string
description: >-
Outcome alias: 'yes' or 'no', or an outcome token ID. When set, the
first argument is treated as a market ID and this value selects
which outcome's order book to fetch. Accepts the literal strings
'yes'/'no' (resolved via a market lookup) or a raw outcome token ID.
- in: query
name: since
required: false
schema:
type: number
description: >-
Unix timestamp (ms) — fetch a historical snapshot at or before this
time, or the start of a range when combined with `until` (hosted API
only).
- in: query
name: until
required: false
schema:
type: number
description: >-
Unix timestamp (ms) — end of a historical range. When combined with
`since`, returns an array of reconstructed L2 OrderBook snapshots
between `since` and `until` (hosted API only).
responses:
'200':
description: Fetch Order Book response
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/BaseResponse'
- type: object
properties:
data:
$ref: '#/components/schemas/OrderBook'
security: []
x-codeSamples:
- lang: python
label: Polymarket
source: |-
import pmxt
# API key optional — enables faster catalog-backed lookups
exchange = pmxt.Polymarket(
pmxt_api_key="YOUR_PMXT_API_KEY",
)
result = exchange.fetch_order_book(
"67890",
limit=10,
params={"outcome": "yes"},
)
- lang: python
label: Limitless
source: |-
import pmxt
# API key optional — enables faster catalog-backed lookups
exchange = pmxt.Limitless(
pmxt_api_key="YOUR_PMXT_API_KEY",
)
result = exchange.fetch_order_book(
"67890",
limit=10,
params={"outcome": "yes"},
)
- lang: python
label: Kalshi
source: |-
import pmxt
# API key optional — enables faster catalog-backed lookups
exchange = pmxt.Kalshi(
pmxt_api_key="YOUR_PMXT_API_KEY",
)
result = exchange.fetch_order_book(
"67890",
limit=10,
params={"outcome": "yes"},
)
- lang: python
label: KalshiDemo
source: |-
import pmxt
# API key optional — enables faster catalog-backed lookups
exchange = pmxt.KalshiDemo(
pmxt_api_key="YOUR_PMXT_API_KEY",
)
result = exchange.fetch_order_book(
"67890",
limit=10,
params={"outcome": "yes"},
)
- lang: python
label: Probable
source: |-
import pmxt
# API key optional — enables faster catalog-backed lookups
exchange = pmxt.Probable(
pmxt_api_key="YOUR_PMXT_API_KEY",
)
result = exchange.fetch_order_book(
"67890",
limit=10,
params={"outcome": "yes"},
)
- lang: python
label: Baozi
source: |-
import pmxt
# API key optional — enables faster catalog-backed lookups
exchange = pmxt.Baozi(
pmxt_api_key="YOUR_PMXT_API_KEY",
)
result = exchange.fetch_order_book(
"67890",
limit=10,
params={"outcome": "yes"},
)
- lang: python
label: Myriad
source: |-
import pmxt
# API key optional — enables faster catalog-backed lookups
exchange = pmxt.Myriad(
pmxt_api_key="YOUR_PMXT_API_KEY",
)
result = exchange.fetch_order_book(
"67890",
limit=10,
params={"outcome": "yes"},
)
- lang: python
label: Opinion
source: |-
import pmxt
# API key optional — enables faster catalog-backed lookups
exchange = pmxt.Opinion(
pmxt_api_key="YOUR_PMXT_API_KEY",
)
result = exchange.fetch_order_book(
"67890",
limit=10,
params={"outcome": "yes"},
)
- lang: python
label: Metaculus
source: |-
import pmxt
# API key optional — enables faster catalog-backed lookups
exchange = pmxt.Metaculus(
pmxt_api_key="YOUR_PMXT_API_KEY",
)
result = exchange.fetch_order_book(
"67890",
limit=10,
params={"outcome": "yes"},
)
- lang: python
label: Smarkets
source: |-
import pmxt
# API key optional — enables faster catalog-backed lookups
exchange = pmxt.Smarkets(
pmxt_api_key="YOUR_PMXT_API_KEY",
)
result = exchange.fetch_order_book(
"67890",
limit=10,
params={"outcome": "yes"},
)
- lang: python
label: PolymarketUS
source: |-
import pmxt
# API key optional — enables faster catalog-backed lookups
exchange = pmxt.PolymarketUS(
pmxt_api_key="YOUR_PMXT_API_KEY",
)
result = exchange.fetch_order_book(
"67890",
limit=10,
params={"outcome": "yes"},
)
- lang: python
label: Hyperliquid
source: |-
import pmxt
# API key optional — enables faster catalog-backed lookups
exchange = pmxt.Hyperliquid(
pmxt_api_key="YOUR_PMXT_API_KEY",
)
result = exchange.fetch_order_book(
"67890",
limit=10,
params={"outcome": "yes"},
)
- lang: python
label: GeminiTitan
source: |-
import pmxt
# API key optional — enables faster catalog-backed lookups
exchange = pmxt.GeminiTitan(
pmxt_api_key="YOUR_PMXT_API_KEY",
)
result = exchange.fetch_order_book(
"67890",
limit=10,
params={"outcome": "yes"},
)
- lang: python
label: SuiBets
source: |-
import pmxt
# API key optional — enables faster catalog-backed lookups
exchange = pmxt.SuiBets(
pmxt_api_key="YOUR_PMXT_API_KEY",
)
result = exchange.fetch_order_book(
"67890",
limit=10,
params={"outcome": "yes"},
)
- lang: python
label: Rain
source: |-
import pmxt
# API key optional — enables faster catalog-backed lookups
exchange = pmxt.Rain(
pmxt_api_key="YOUR_PMXT_API_KEY",
)
result = exchange.fetch_order_book(
"67890",
limit=10,
params={"outcome": "yes"},
)
- lang: python
label: Hunch
source: |-
import pmxt
# API key optional — enables faster catalog-backed lookups
exchange = pmxt.Hunch(
pmxt_api_key="YOUR_PMXT_API_KEY",
)
result = exchange.fetch_order_book(
"67890",
limit=10,
params={"outcome": "yes"},
)
- lang: javascript
label: Polymarket
source: |-
import { Polymarket } from "pmxtjs";
// API key optional — enables faster catalog-backed lookups
const exchange = new Polymarket({
pmxtApiKey: "YOUR_PMXT_API_KEY",
});
const result = await exchange.fetchOrderBook(
"67890",
10,
{ outcome: "yes" },
);
- lang: javascript
label: Limitless
source: |-
import { Limitless } from "pmxtjs";
// API key optional — enables faster catalog-backed lookups
const exchange = new Limitless({
pmxtApiKey: "YOUR_PMXT_API_KEY",
});
const result = await exchange.fetchOrderBook(
"67890",
10,
{ outcome: "yes" },
);
- lang: javascript
label: Kalshi
source: |-
import { Kalshi } from "pmxtjs";
// API key optional — enables faster catalog-backed lookups
const exchange = new Kalshi({
pmxtApiKey: "YOUR_PMXT_API_KEY",
});
const result = await exchange.fetchOrderBook(
"67890",
10,
{ outcome: "yes" },
);
- lang: javascript
label: KalshiDemo
source: |-
import { KalshiDemo } from "pmxtjs";
// API key optional — enables faster catalog-backed lookups
const exchange = new KalshiDemo({
pmxtApiKey: "YOUR_PMXT_API_KEY",
});
const result = await exchange.fetchOrderBook(
"67890",
10,
{ outcome: "yes" },
);
- lang: javascript
label: Probable
source: |-
import { Probable } from "pmxtjs";
// API key optional — enables faster catalog-backed lookups
const exchange = new Probable({
pmxtApiKey: "YOUR_PMXT_API_KEY",
});
const result = await exchange.fetchOrderBook(
"67890",
10,
{ outcome: "yes" },
);
- lang: javascript
label: Baozi
source: |-
import { Baozi } from "pmxtjs";
// API key optional — enables faster catalog-backed lookups
const exchange = new Baozi({
pmxtApiKey: "YOUR_PMXT_API_KEY",
});
const result = await exchange.fetchOrderBook(
"67890",
10,
{ outcome: "yes" },
);
- lang: javascript
label: Myriad
source: |-
import { Myriad } from "pmxtjs";
// API key optional — enables faster catalog-backed lookups
const exchange = new Myriad({
pmxtApiKey: "YOUR_PMXT_API_KEY",
});
const result = await exchange.fetchOrderBook(
"67890",
10,
{ outcome: "yes" },
);
- lang: javascript
label: Opinion
source: |-
import { Opinion } from "pmxtjs";
// API key optional — enables faster catalog-backed lookups
const exchange = new Opinion({
pmxtApiKey: "YOUR_PMXT_API_KEY",
});
const result = await exchange.fetchOrderBook(
"67890",
10,
{ outcome: "yes" },
);
- lang: javascript
label: Metaculus
source: |-
import { Metaculus } from "pmxtjs";
// API key optional — enables faster catalog-backed lookups
const exchange = new Metaculus({
pmxtApiKey: "YOUR_PMXT_API_KEY",
});
const result = await exchange.fetchOrderBook(
"67890",
10,
{ outcome: "yes" },
);
- lang: javascript
label: Smarkets
source: |-
import { Smarkets } from "pmxtjs";
// API key optional — enables faster catalog-backed lookups
const exchange = new Smarkets({
pmxtApiKey: "YOUR_PMXT_API_KEY",
});
const result = await exchange.fetchOrderBook(
"67890",
10,
{ outcome: "yes" },
);
- lang: javascript
label: PolymarketUS
source: |-
import { PolymarketUS } from "pmxtjs";
// API key optional — enables faster catalog-backed lookups
const exchange = new PolymarketUS({
pmxtApiKey: "YOUR_PMXT_API_KEY",
});
const result = await exchange.fetchOrderBook(
"67890",
10,
{ outcome: "yes" },
);
- lang: javascript
label: Hyperliquid
source: |-
import { Hyperliquid } from "pmxtjs";
// API key optional — enables faster catalog-backed lookups
const exchange = new Hyperliquid({
pmxtApiKey: "YOUR_PMXT_API_KEY",
});
const result = await exchange.fetchOrderBook(
"67890",
10,
{ outcome: "yes" },
);
- lang: javascript
label: GeminiTitan
source: |-
import { GeminiTitan } from "pmxtjs";
// API key optional — enables faster catalog-backed lookups
const exchange = new GeminiTitan({
pmxtApiKey: "YOUR_PMXT_API_KEY",
});
const result = await exchange.fetchOrderBook(
"67890",
10,
{ outcome: "yes" },
);
- lang: javascript
label: SuiBets
source: |-
import { SuiBets } from "pmxtjs";
// API key optional — enables faster catalog-backed lookups
const exchange = new SuiBets({
pmxtApiKey: "YOUR_PMXT_API_KEY",
});
const result = await exchange.fetchOrderBook(
"67890",
10,
{ outcome: "yes" },
);
- lang: javascript
label: Rain
source: |-
import { Rain } from "pmxtjs";
// API key optional — enables faster catalog-backed lookups
const exchange = new Rain({
pmxtApiKey: "YOUR_PMXT_API_KEY",
});
const result = await exchange.fetchOrderBook(
"67890",
10,
{ outcome: "yes" },
);
- lang: javascript
label: Hunch
source: |-
import { Hunch } from "pmxtjs";
// API key optional — enables faster catalog-backed lookups
const exchange = new Hunch({
pmxtApiKey: "YOUR_PMXT_API_KEY",
});
const result = await exchange.fetchOrderBook(
"67890",
10,
{ outcome: "yes" },
);
components:
parameters:
ExchangeParam:
in: path
name: exchange
schema:
type: string
enum:
- polymarket
- kalshi
- kalshi-demo
- limitless
- probable
- baozi
- myriad
- opinion
- metaculus
- smarkets
- polymarket_us
- gemini-titan
- hyperliquid
- suibets
- rain
- hunch
- router
required: true
description: The prediction market exchange to target.
schemas:
BaseResponse:
type: object
properties:
success:
type: boolean
example: true
error:
$ref: '#/components/schemas/ErrorDetail'
OrderBook:
type: object
properties:
bids:
type: array
items:
$ref: '#/components/schemas/OrderLevel'
description: Order book bid levels, sorted by price descending.
asks:
type: array
items:
$ref: '#/components/schemas/OrderLevel'
description: Order book ask levels, sorted by price ascending.
timestamp:
type: number
description: Unix timestamp in milliseconds when the snapshot was taken.
datetime:
type: string
description: ISO 8601 datetime string of the snapshot (CCXT-compatible).
isNegRisk:
type: boolean
description: Whether the venue marks this snapshot as a negative-risk market.
lastTradePrice:
type: number
description: >-
Last traded price from venues that include it with the book
snapshot.
sourceMetadata:
type: object
additionalProperties: {}
description: Venue-specific metadata preserved from the raw order book snapshot.
required:
- bids
- asks
ErrorDetail:
type: object
description: >-
Structured error envelope returned inside `BaseResponse.error` and
`ErrorResponse.error`. Hosted-mode endpoints populate `code`,
`retryable`, and optionally `exchange` / `detail`; legacy local-mode
endpoints may still return only `message`.
properties:
message:
type: string
description: Human-readable error message.
code:
type: string
description: >-
Stable machine-readable error code. Hosted-mode errors use the
`HostedTradingError` family (e.g. `INSUFFICIENT_ESCROW_BALANCE`,
`BUILT_ORDER_EXPIRED`); pre-hosted local errors use the legacy
family (e.g. `BAD_REQUEST`, `NOT_FOUND`).
enum:
- HOSTED_TRADING_ERROR
- INSUFFICIENT_ESCROW_BALANCE
- ORDER_SIZE_TOO_SMALL
- INVALID_API_KEY
- OUTCOME_NOT_FOUND
- CATALOG_UNAVAILABLE
- BUILT_ORDER_EXPIRED
- INVALID_SIGNATURE
- NO_LIQUIDITY
- MISSING_WALLET_ADDRESS
- BAD_REQUEST
- AUTHENTICATION_ERROR
- PERMISSION_DENIED
- NOT_FOUND
- ORDER_NOT_FOUND
- MARKET_NOT_FOUND
- EVENT_NOT_FOUND
- RATE_LIMIT_EXCEEDED
- INVALID_ORDER
- INSUFFICIENT_FUNDS
- VALIDATION_ERROR
- NETWORK_ERROR
- EXCHANGE_NOT_AVAILABLE
- NOT_SUPPORTED
retryable:
type: boolean
description: >-
Hint for clients: when `true`, the same request may succeed on retry
(e.g. transient network or rate-limit conditions); when `false`, the
caller should not retry without modifying the request.
exchange:
type: string
nullable: true
description: >-
Venue the error originated from, when known (e.g. 'polymarket',
'kalshi').
detail:
type: object
additionalProperties: {}
nullable: true
description: >-
Free-form hosted-mode detail blob. Shape depends on `code` — e.g.
for `INSUFFICIENT_ESCROW_BALANCE` it may include `{ requested,
available }`; for `ORDER_SIZE_TOO_SMALL` it may include `{ min }`;
for `BUILT_ORDER_EXPIRED` it may include `{ expiry }`.
OrderLevel:
type: object
properties:
price:
type: number
description: 0.0 to 1.0 (probability)
size:
type: number
description: contracts/shares
orderCount:
type: number
required:
- price
- size
````