Get Polymarket Orderbook Summary

Retrieve a bucketed best bid/best ask time series for a Polymarket market condition on a UTC date or custom timestamp window.

GET /api/v1/polymarket/market/orderbook-summary

Get Polymarket Orderbook Summary

cURL

curl --request GET \
  --url https://api.entityml.com/api/v1/polymarket/market/orderbook-summary \
  --header 'Authorization: <authorization>'

200

{
  "market_condition_id": "<string>",
  "asset_id": "<string>",
  "date": "<string>",
  "resolution_seconds": 123,
  "data_points": 123,
  "data": [
    {
      "timestamp": 123,
      "quote_count": 123,
      "is_forward_filled": true,
      "best_bid": 123,
      "best_bid_size": 123,
      "best_ask": 123,
      "best_ask_size": 123,
      "mid_price": 123,
      "spread": 123,
      "best_bid_ohlc": {},
      "best_ask_ohlc": {},
      "mid_price_ohlc": {},
      "spread_ohlc": {}
    }
  ]
}

Request

Headers

Authorization · string · required

Bearer token. Example: Bearer YOUR_API_KEY

Query Parameters

condition_id · string · required

The Polymarket market condition ID. Values are accepted with or without the 0x prefix.

asset_id · string · required

CLOB token ID to summarize within the condition. Polymarket conditions can have multiple outcome token books, so this parameter is required.

To find asset_id values, request a small page from Get Polymarket Market Data and collect the unique asset_id fields. See Examples.

date · string

The UTC date to summarize, formatted as YYYY-MM-DD. Required unless start_timestamp and end_timestamp are provided.

start_timestamp · integer

Inclusive lower timestamp bound in Unix seconds or milliseconds. Must be provided with end_timestamp.

end_timestamp · integer

Inclusive upper timestamp bound in Unix seconds or milliseconds. Must be provided with start_timestamp.

resolution · integer

Time bucket resolution in seconds. Default: 60. Valid range: 1 to 3600.

Use date for a full UTC day, or use start_timestamp and end_timestamp for a custom UTC window. Custom windows hydrate book state from earlier records in the loaded UTC date partitions and emit buckets inside the requested range.

Response

market_condition_id · string

The Polymarket market condition ID.

asset_id · string

The CLOB token ID used for the summary.

date · string

The requested date.

resolution_seconds · integer

The bucket size used to build the summary.

data_points · integer

Number of summary points returned.

data · array

Array of time buckets. Each bucket includes close values and OHLC candles:

Show Bucket fields

timestamp · integer

Bucket start timestamp in Unix milliseconds.

quote_count · integer

Number of reconstructed top-of-book observations in this bucket. Forward-filled buckets use 0.

is_forward_filled · boolean

true when no quote was observed in this bucket and values were carried forward from the previous bucket.

best_bid · number

Close value for the best bid in this bucket.

best_bid_size · number

Close size for the best bid in this bucket.

best_ask · number

Close value for the best ask in this bucket.

best_ask_size · number

Close size for the best ask in this bucket.

mid_price · number

Close midpoint, computed as (best_bid + best_ask) / 2 when both sides are present.

spread · number

Close spread, computed as best_ask - best_bid when both sides are present.

best_bid_ohlc · object

OHLC values for every best-bid quote observed inside the bucket.

best_ask_ohlc · object

OHLC values for every best-ask quote observed inside the bucket.

mid_price_ohlc · object

OHLC values for every midpoint observed inside the bucket.

spread_ohlc · object

OHLC values for every spread observed inside the bucket.

The legacy alias GET /api/v1/market/orderbook-summary remains available for existing integrations.

Example

Python SDK

from entityml import EntityMLClient

client = EntityMLClient(api_key="YOUR_API_KEY")

summary = client.polymarket.get_orderbook_summary(
    condition_id="0x8213d395e079614d6c4d7f4cbb9be9337ab51648a21cc2a334ae8f1966d164b4",
    asset_id="97684905927345553455494278582909124912046930226695064344571162061840768197777",
    start_timestamp=1770940800000,
    end_timestamp=1770944399999,
    resolution=60,
)

print(summary["data_points"])

Example response

{
  "market_condition_id": "0x8213d395e079614d6c4d7f4cbb9be9337ab51648a21cc2a334ae8f1966d164b4",
  "asset_id": "97684905927345553455494278582909124912046930226695064344571162061840768197777",
  "date": null,
  "start_timestamp": 1770940800000,
  "end_timestamp": 1770944399999,
  "resolution_seconds": 60,
  "data_points": 1440,
  "data": [
    {
      "timestamp": 1770940800000,
      "quote_count": 42,
      "is_forward_filled": false,
      "best_bid": 0.12,
      "best_bid_size": 4361.9,
      "best_ask": 0.15,
      "best_ask_size": 4361.9,
      "mid_price": 0.135,
      "spread": 0.03,
      "best_bid_ohlc": { "open": 0.11, "high": 0.12, "low": 0.1, "close": 0.12 },
      "best_ask_ohlc": { "open": 0.16, "high": 0.16, "low": 0.15, "close": 0.15 },
      "mid_price_ohlc": { "open": 0.135, "high": 0.14, "low": 0.125, "close": 0.135 },
      "spread_ohlc": { "open": 0.05, "high": 0.06, "low": 0.03, "close": 0.03 }
    }
  ]
}