Get order book history

Paginated history of raw CLOB orderbook snapshots including full bids/asks levels and derived metrics. Default limit 20, max 200. bids and asks are arrays of {"p": price, "s": size} objects, sorted best-first.

GET /polymarket/order-book/history

Get order book history

cURL

curl --request GET \
  --url https://api.struct.to/v1/polymarket/order-book/history

200

[
  {
    "ts": 123,
    "position_id": "<string>",
    "condition_id": "<string>",
    "bids": [
      {
        "p": "<string>",
        "s": "<string>"
      }
    ],
    "asks": [
      {
        "p": "<string>",
        "s": "<string>"
      }
    ],
    "hash": "<string>",
    "best_bid": 123,
    "best_ask": 123,
    "mid_price": 123,
    "spread": 123,
    "bid_liquidity_usd": 123,
    "ask_liquidity_usd": 123,
    "bid_levels": 123,
    "ask_levels": 123
  }
]

Query Parameters

position_id · string

Token ID (required if condition_id / market_slug not set)

condition_id · string

Condition ID — returns history for all positions in this market

market_slug · string

Market slug (alternative to condition_id)

from · integer<int64>

Start timestamp (Unix milliseconds, inclusive)

to · integer<int64>

End timestamp (Unix milliseconds, inclusive)

min_spread · number<double>

Only return snapshots with spread >= this value

max_spread · number<double>

Only return snapshots with spread <= this value

min_liquidity · number<double>

Only return snapshots where total liquidity (bid + ask) >= this value

limit · integer<int64>

Number of results (default: 20, max: 200)

pagination_key · string

Cursor from previous response's pagination.pagination_key

Response

200

application/json

Orderbook snapshot rows, newest first. ts is Unix milliseconds.

ts · integer<int64> · required

Unix timestamp in seconds.

position_id · string · required

Position ID.

condition_id · string · required

Condition ID.

bids · object[] · required

Bid levels for the order book.

Show child attributes

asks · object[] · required

Ask levels for the order book.

Show child attributes

hash · string · required

Order book snapshot hash.

best_bid · number<double> | null

Best bid.

best_ask · number<double> | null

Best ask.

mid_price · number<double> | null

Mid price.

spread · number<double> | null

Spread.

bid_liquidity_usd · number<double> | null

Bid liquidity in USD.

ask_liquidity_usd · number<double> | null

Ask liquidity in USD.

bid_levels · integer<int32> | null

Bid levels.

ask_levels · integer<int32> | null

Ask levels.