Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.poly-data.xyz/llms.txt

Use this file to discover all available pages before exploring further.

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]]
}
FieldTypeDescription
tsintegerUnix timestamp in milliseconds
asset_idstringToken ID for the outcome
market_idstringMarket ID
outcome_indexintegerOutcome position (0 = first outcome, typically “Yes”)
bidsarrayBuy orders as [price, size] tuples, sorted by price descending
asksarraySell orders as [price, size] tuples, sorted by price ascending

​
Query Orderbooks

​
GET
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

​
market_id
string
Filter by market ID.
​
asset_id
string
Filter by asset/token ID.
​
outcome
string
Filter by outcome. Accepts yes, no, 0, or 1.
​
from
integer
Start timestamp in milliseconds (inclusive).
​
to
integer
End timestamp in milliseconds (inclusive).
​
limit
integer
default:"100"
Results per page (1–1000).
​
cursor_ts
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
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

​
market_id
string
Filter by market ID.
​
asset_id
string
Filter by asset/token ID.
​
outcome
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

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

​
Path Parameters

​
market_id
string
required
Market ID.

​
Query Parameters

​
outcome
string
Filter by outcome. Accepts yes, no, 0, or 1.
​
from
integer
Start timestamp in milliseconds (inclusive).
​
to
integer
End timestamp in milliseconds (inclusive).
​
limit
integer
default:"100"
Results per page (1–1000).
​
cursor_ts
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.