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).

GET /api/{exchange}/fetchOrderBook

Python

Polymarket

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"}, )

200

{
  "success": true,
  "error": {
    "message": "<string>",
    "code": "HOSTED_TRADING_ERROR",
    "retryable": true,
    "exchange": "<string>",
    "detail": {}
  },
  "data": {
    "bids": [
      {
        "price": 123,
        "size": 123,
        "orderCount": 123
      }
    ],
    "asks": [
      {
        "price": 123,
        "size": 123,
        "orderCount": 123
      }
    ],
    "timestamp": 123,
    "datetime": "<string>",
    "isNegRisk": true,
    "lastTradePrice": 123,
    "sourceMetadata": {}
  }
}

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

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")

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

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}")

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

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}")

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 instead of trying to stream bulk data through the live order book endpoint.

Python

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}")

Historical order book data is backed by the PMXT Archive — 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.

Path Parameters

exchange · enum<string> · required

The prediction market exchange to target.

Available options: polymarket, kalshi, kalshi-demo, limitless, probable, baozi, myriad, opinion, metaculus, smarkets, polymarket_us, gemini-titan, hyperliquid, suibets, rain, hunch, router

Query Parameters

outcomeId · string · required

limit · number

side · enum<string>

Outcome side: 'yes' or 'no'. Required for exchanges like Limitless where the API returns a single orderbook per market.

Available options: yes, no

outcome · string

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.

since · number

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).

until · number

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).

Response

200 - application/json

Fetch Order Book response

success · boolean

Example:

true

error · object

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.

Show child attributes

data · object

Show child attributes