How do I get Polymarket order book historical data?

Call GET /v1/markets/{market_id}/orderbook for a current snapshot, or orderbook.walk() in the Python SDK to replay historical books tick-by-tick. Bulk CSV/Parquet exports are available at marketlens.trade/docs/exports.

What resolution is the Polymarket order book data?

Full L2 order book snapshots are captured every ~60 seconds, with millisecond-resolution price_change deltas chained between snapshots. Reconstructing book state at any tick is exact.

Can I replay a Polymarket orderbook at a specific timestamp?

Yes. orderbook.walk(market_id, after=..., before=...) yields reconstructed book states tick-by-tick. The same replay powers the backtest harness.

Does the API return bid/ask sizes or just prices?

Both. Every level includes price and size (USD). Depth, spread, and midpoint are exposed as derived metrics via /orderbook/metrics.

Data

Order Book

Reconstruct L2 order books at any point in time, stream raw events, or query aggregated metrics. All prices are YES-centric with 4-decimal precision.

GET/markets/{market_id}/orderbook

sdkclient.orderbook.get(market_id, **params)

Reconstruct the full L2 order book at a given timestamp. Defaults to the latest available state.

Parameters

market_idstrrequired

Market UUID.

atint | str

Target timestamp (ms epoch or ISO 8601). Defaults to latest.

depthint

Max levels per side (1-100). Summary metrics always computed from full book.

book = client.orderbook.get(
    "4ee145e2-3fee-5b15-bb95-56a33a292945",
    depth=10,
)
print(book.best_bid, book.best_ask, book.spread)
print(f"{book.bid_depth} USD on bids")

jsonResponse

{
  "data": {
    "market_id": "8150b888...",
    "platform": "polymarket",
    "as_of": 1710400000000,
    "bids": [
      { "price": 0.6200, "size": 1250.0000 },
      { "price": 0.6100, "size": 3400.0000 }
    ],
    "asks": [
      { "price": 0.6300, "size": 980.0000 },
      { "price": 0.6400, "size": 2100.0000 }
    ],
    "best_bid": 0.6200,
    "best_ask": 0.6300,
    "spread": 0.0100,
    "midpoint": 0.6250,
    "bid_depth": 18230.0000,
    "ask_depth": 15440.0000,
    "bid_levels": 42,
    "ask_levels": 38
  }
}

GET/markets/{market_id}/orderbook/history

sdkclient.orderbook.walk(id, **params)

Stream order book snapshots and deltas over a time range. The SDK's walk() iterator reconstructs full book state at each point, yielding (Market, OrderBook) tuples. Accepts a market UUID, series slug, or condition ID.

walk() parameters

idstrrequired

Market UUID, series slug, or condition ID.

afterstr

Start time (ISO 8601 or ms).

beforestr

End time (ISO 8601 or ms).

Underlying history endpoint params

market_idstrrequired

Market UUID.

afterint | strrequired

Start of time range, exclusive (ms epoch or ISO 8601).

beforeint | strrequired

End of time range, exclusive (ms epoch or ISO 8601).

include_tradesbool= false

Include trade events in the stream.

limitint= 1000

Events per page.

takeint

SDK only. Caps total items returned across pages.

walk = client.orderbook.walk(
    "btc-up-or-down-5m",
    after="2026-04-15T01:45:00Z",
    before="2026-04-15T01:50:00Z",
)
for market, book in walk:
    print(market.question, book.midpoint)

jsonResponse

{
  "market_id": "8150b888-0297-5275-...",
  "platform": "polymarket",
  "data": [
    {
      "type": "snapshot",
      "t": 1710400000000,
      "is_reseed": false,
      "bids": [
        { "price": 0.6200, "size": 1250.0000 },
        { "price": 0.6100, "size": 3400.0000 }
      ],
      "asks": [
        { "price": 0.6300, "size": 980.0000 },
        { "price": 0.6400, "size": 2100.0000 }
      ]
    },
    {
      "type": "delta",
      "t": 1710400001234,
      "price": 0.6200,
      "size": 1580.0000,
      "side": "BUY"
    },
    {
      "type": "delta",
      "t": 1710400002100,
      "price": 0.6300,
      "size": 0.0000,
      "side": "SELL"
    },
    {
      "type": "trade",
      "t": 1710400001500,
      "id": "01HQXYZ...",
      "price": 0.6200,
      "size": 150.0000,
      "side": "BUY"
    }
  ],
  "meta": { "cursor": "eyJ0IjoxNzEwNDAwMDAyfQ", "has_more": true }
}

GET/markets/{market_id}/orderbook/metrics

sdkclient.orderbook.metrics(market_id, **params)

Time-series of aggregated book metrics at a fixed resolution.

Parameters

market_idstrrequired

Market UUID.

afterint | strrequired

Start timestamp (ms epoch or ISO 8601).

beforeint | strrequired

End timestamp (ms epoch or ISO 8601).

resolutionstrrequired

"1m", "5m", "15m", "1h", "4h", or "1d".

orderstr= "asc"

Sort direction: "asc" or "desc".

limitint= 500

Buckets per page.

cursorstr

Pagination cursor.

takeint

SDK only. Caps total items returned across pages.

Max time ranges per resolution: 24h (1m), 7d (5m), 14d (15m), 30d (1h), 90d (4h), 1y (1d).

metrics = client.orderbook.metrics(
    "4ee145e2-3fee-5b15-bb95-56a33a292945",
    after="2026-04-15T01:45:00Z",
    before="2026-04-15T01:50:00Z",
    resolution="1m",
)

jsonResponse

{
  "market_id": "8150b888-67f6-58ed-...",
  "platform": "polymarket",
  "resolution": "5m",
  "data": [
    {
      "t": 1710028800000,
      "best_bid": 0.6200,
      "best_ask": 0.6300,
      "spread": 0.0100,
      "midpoint": 0.6250,
      "bid_depth": 18230.0000,
      "ask_depth": 15440.0000,
      "bid_levels": 42,
      "ask_levels": 38
    },
    {
      "t": 1710029100000,
      "best_bid": 0.6300,
      "best_ask": 0.6400,
      "spread": 0.0100,
      "midpoint": 0.6350,
      "bid_depth": 19100.0000,
      "ask_depth": 14800.0000,
      "bid_levels": 44,
      "ask_levels": 36
    }
  ],
  "meta": {
    "cursor": "eyJ0IjoxNzEwMDI5MTAwMDAwfQ==",
    "has_more": true
  }
}