Orderbooks

The orderbooks endpoints provide access to historical bid/ask data collected from the Polymarket WebSocket feed since January 1, 2026. Each snapshot contains the full orderbook depth at a specific timestamp.

Orderbook endpoints have stricter rate limits: 30 requests per minute.

Data Structure

Each orderbook snapshot contains bid and ask arrays as [price, size] tuples:

{
  "ts": 1768006613042,
  "asset_id": "113230976933674601135419276232321769865636781054804255103253100668166812267778",
  "market_id": "1034460",
  "outcome_index": 0,
  "bids": [[0.55, 1000], [0.54, 2500], [0.53, 5000]],
  "asks": [[0.56, 800], [0.57, 1500], [0.58, 3000]]
}

Field	Type	Description
`ts`	integer	Unix timestamp in milliseconds
`asset_id`	string	Token ID for the outcome
`market_id`	string	Market ID
`outcome_index`	integer	Outcome position (0 = first outcome, typically “Yes”)
`bids`	array	Buy orders as `[price, size]` tuples, sorted by price descending
`asks`	array	Sell orders as `[price, size]` tuples, sorted by price ascending

Query Orderbooks

Query orderbook snapshots with filters. Results are ordered by timestamp descending (most recent first).

At least one of market_id or asset_id is required.

Query Parameters

string

Filter by market ID.

string

Filter by asset/token ID.

string

Filter by outcome. Accepts yes, no, 0, or 1.

integer

Start timestamp in milliseconds (inclusive).

integer

End timestamp in milliseconds (inclusive).

integer

default:"100"

Results per page (1–1000).

integer

Timestamp cursor for pagination. Returns rows with ts < cursor_ts.

Examples

Get orderbook history for a market:

curl "http://api.poly-data.xyz/orderbooks?market_id=1034460&limit=50"

Get orderbooks within a specific time range:

curl "http://api.poly-data.xyz/orderbooks?market_id=1034460&from=1767290000000&to=1768010000000"

Filter by “Yes” outcome:

curl "http://api.poly-data.xyz/orderbooks?market_id=1034460&outcome=yes&limit=100"

Response:

{
  "filters": {
    "market_id": "1034460",
    "asset_id": null,
    "outcome": null,
    "from": null,
    "to": null
  },
  "limit": 100,
  "count": 100,
  "next": {
    "cursor_ts": 1767950000000
  },
  "data": [
    {
      "ts": 1768006613042,
      "asset_id": "113230976933674...",
      "market_id": "1034460",
      "outcome_index": 0,
      "bids": [[0.55, 1000], [0.54, 2500]],
      "asks": [[0.56, 800], [0.57, 1500]]
    }
  ]
}

Get Latest Orderbook

Get the most recent orderbook snapshot for a market or asset.

At least one filter parameter (market_id, asset_id, or outcome) is required.

Query Parameters

string

Filter by market ID.

string

Filter by asset/token ID.

string

Filter by outcome. Accepts yes, no, 0, or 1.

Examples

Get latest orderbook for a market:

curl "http://api.poly-data.xyz/orderbooks/latest?market_id=1034460"

Get latest orderbook for a specific token:

curl "http://api.poly-data.xyz/orderbooks/latest?asset_id=113230976933674601135419276232321769865636781054804255103253100668166812267778"

Response:

{
  "ts": 1768006613042,
  "asset_id": "113230976933674601135419276232321769865636781054804255103253100668166812267778",
  "market_id": "1034460",
  "outcome_index": 0,
  "bids": [[0.55, 1000], [0.54, 2500], [0.53, 5000]],
  "asks": [[0.56, 800], [0.57, 1500], [0.58, 3000]]
}

This endpoint has a 500ms cache TTL for near real-time data access.

Get Orderbooks by Market ID

Convenience endpoint to get orderbook snapshots for a specific market. Results are ordered by timestamp descending.

Path Parameters

string

required

Market ID.

Query Parameters

string

Filter by outcome. Accepts yes, no, 0, or 1.

integer

Start timestamp in milliseconds (inclusive).

integer

End timestamp in milliseconds (inclusive).

integer

default:"100"

Results per page (1–1000).

integer

Timestamp cursor for pagination. Returns rows with ts < cursor_ts.

Example

curl "http://api.poly-data.xyz/orderbooks/1034460?limit=100"

Response:

{
  "market_id": "1034460",
  "filters": {
    "outcome": null,
    "from": null,
    "to": null
  },
  "limit": 100,
  "count": 100,
  "next": {
    "cursor_ts": 1767950000000
  },
  "data": [
    {
      "ts": 1768006613042,
      "asset_id": "113230976933674...",
      "market_id": "1034460",
      "outcome_index": 0,
      "bids": [[0.55, 1000], [0.54, 2500]],
      "asks": [[0.56, 800], [0.57, 1500]]
    }
  ]
}

Pagination Example

For large historical queries, use cursor-based pagination. Start with a very high cursor_ts value and follow the next cursor:

import requests
import time

market_id = "1034460"
all_orderbooks = []
cursor_ts = "9999999999999"

while True:
    params = {"limit": 100, "cursor_ts": cursor_ts}

    response = requests.get(
        f"http://api.poly-data.xyz/orderbooks/{market_id}",
        params=params
    )

    if response.status_code == 429:
        print("Rate limited, waiting 60s...")
        time.sleep(60)
        continue

    data = response.json()

    if "data" not in data:
        print(f"Unexpected response: {data}")
        break

    all_orderbooks.extend(data["data"])
    print(f"Fetched {len(data['data'])} rows (total: {len(all_orderbooks)})")

    if data.get("next") and data["next"].get("cursor_ts"):
        cursor_ts = data["next"]["cursor_ts"]
    else:
        break

    time.sleep(0.1)  # Be kind to the API

print(f"Retrieved {len(all_orderbooks)} orderbook snapshots")

Add a small delay between requests (e.g., time.sleep(0.1)) to avoid hitting the 30 requests/minute rate limit.

Common Use Cases

Backtesting

Fetch historical orderbooks within a time range to simulate trading strategies.

Spread Analysis

Calculate bid-ask spreads over time to analyze market liquidity.

Event Studies

Study how orderbooks change around major news events.

Market Making

Analyze historical depth to calibrate market making parameters.

Overview

Endpoints

Data Structure

Query Orderbooks

Query Parameters

Examples

Get Latest Orderbook

Query Parameters

Examples

Get Orderbooks by Market ID

Path Parameters

Query Parameters

Example

Common Use Cases

Backtesting

Spread Analysis

Event Studies

Market Making

​Data Structure

​Query Orderbooks

​Query Parameters

​Examples

​Get Latest Orderbook

​Query Parameters

​Examples

​Get Orderbooks by Market ID

​Path Parameters

​Query Parameters

​Example

​Pagination Example

​Common Use Cases

Backtesting

Spread Analysis

Event Studies

Market Making

Data Structure

Query Orderbooks

Query Parameters

Examples

Get Latest Orderbook

Query Parameters

Examples

Get Orderbooks by Market ID

Path Parameters

Query Parameters

Example

Pagination Example

Common Use Cases