Skip to main content
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": 1706000000000,
  "asset_id": "abc123...",
  "market_id": "5001",
  "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)
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.
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 name (e.g., “Yes”, “No”)
​
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

​
Examples

Get orderbook history for a market: 
curl "https://poly-data.xyz/orderbooks?market_id=5001&limit=50"
Get orderbooks within a specific time range: 
curl "https://poly-data.xyz/orderbooks?market_id=5001&from=1705900000000&to=1706000000000"
Filter by outcome: 
curl "https://poly-data.xyz/orderbooks?market_id=5001&outcome=Yes&limit=100"
Response: 
{
  "market_id": "5001",
  "limit": 100,
  "count": 100,
  "next": {
    "cursor_ts": 1705899000000
  },
  "data": [
    {
      "ts": 1705950000000,
      "asset_id": "abc123...",
      "market_id": "5001",
      "outcome_index": 0,
      "bids": [[0.55, 1000], [0.54, 2500], [0.53, 5000]],
      "asks": [[0.56, 800], [0.57, 1500], [0.58, 3000]]
    }
  ]
}

​
Get Latest Orderbook

​
GET
Get the most recent orderbook snapshot for a market or asset.
At least one filter parameter is required.

​
Query Parameters

​
market_id
string
Filter by market ID
​
asset_id
string
Filter by asset/token ID
​
outcome
string
Filter by outcome name

​
Examples

Get latest orderbook for a market: 
curl "https://poly-data.xyz/orderbooks/latest?market_id=5001"
Get latest orderbook for a specific token: 
curl "https://poly-data.xyz/orderbooks/latest?asset_id=abc123..."
Response: 
{
  "ts": 1706000000000,
  "asset_id": "abc123...",
  "market_id": "5001",
  "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.

​
Path Parameters

​
market_id
string
required
Market ID

​
Query Parameters

​
outcome
string
Filter by outcome name
​
from
integer
Start timestamp in milliseconds
​
to
integer
End timestamp in milliseconds
​
limit
integer
default:"100"
Results per page (1-1000)
​
cursor_ts
integer
Timestamp cursor for pagination

​
Example

curl "https://poly-data.xyz/orderbooks/5001?limit=100&from=1705900000000"

​
Pagination Example

For large historical queries, use cursor-based pagination: 
import requests

market_id = "5001"
all_orderbooks = []
cursor_ts = None

while True:
    params = {"market_id": market_id, "limit": 1000}
    if cursor_ts:
        params["cursor_ts"] = cursor_ts
    
    response = requests.get("https://poly-data.xyz/orderbooks", params=params)
    data = response.json()
    
    all_orderbooks.extend(data["data"])
    
    if data.get("next") and data["next"].get("cursor_ts"):
        cursor_ts = data["next"]["cursor_ts"]
    else:
        break

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

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