API
Polymarket order book API: pull historical L2 books
Full bid/ask depth for Polymarket crypto markets, captured every second. This guide covers the /v1/markets/{slug}/books endpoint — what each row contains, how resolution works, query parameters, and how to combine it with the prices and metrics endpoints for a complete market picture.
What this guide covers
- 1-second L2 bid/ask ladders — not midpoints or top-of-book
- Resolved markets stay queryable with the winning outcome on every row
- GET /v1/markets/{slug}/books returns full L2 at query resolution (60s to 1s)
- Free Starter tier includes order books with 3 days of history
How the order book endpoint works
The PolyOrderbooks REST API serves historical L2 order book snapshots for Polymarket crypto Up/Down markets. Each response is an array of snapshots, one per second (at 1s resolution), containing the full bid/ask ladder at that moment.
Unlike Polymarket's own CLOB API — which serves live order books that change every tick — PolyOrderbooks captures and stores the complete book state at regular intervals. This means you can query the exact book that existed at any point in a market's history, not just the current state.
The endpoint accepts three required parameters: start_ts (Unix seconds), end_ts (Unix seconds), and resolution (how finely to return data points). Resolution options range from 60s down to 1s. At 1s resolution, every second of the market's life is captured as a separate snapshot.
Each snapshot contains aligned bids and asks arrays sorted by price level. Bids are sorted descending (best bid first), asks ascending (best ask first). Each price level carries a price (0–1 for binary outcomes) and size (number of shares at that level).
| Field | Type | Description |
|---|---|---|
| timestamp | integer | Unix seconds — the moment this snapshot was captured |
| bids | array | Price levels on the bid side, sorted best-to-worst |
| asks | array | Price levels on the ask side, sorted best-to-worst |
| bids[].price | float | Bid price (0–1, where 1 = certain outcome) |
| bids[].size | float | Number of shares available at this price level |
| asks[].price | float | Ask price (0–1) |
| asks[].size | float | Number of shares offered at this price level |
import requests
BASE = "https://api.polyorderbooks.com/v1"
HEADERS = {"X-API-Key": "your-key"}
# Fetch 1-minute of 1s L2 books for a resolved BTC 5m market
r = requests.get(
f"{BASE}/markets/btc-updown-5m-1787486400/books",
headers=HEADERS,
params={
"start_ts": 1787486400,
"end_ts": 1787486700,
"resolution": "1s",
},
)
r.raise_for_status()
snapshots = r.json()
# Each snapshot has 'bids' and 'asks' arrays
for snap in snapshots[:3]:
best_bid = snap["bids"][0]["price"] if snap["bids"] else None
best_ask = snap["asks"][0]["price"] if snap["asks"] else None
spread = best_ask - best_bid if best_bid and best_ask else None
print(f"t={snap['timestamp']} bid={best_bid} ask={best_ask} spread={spread}")Combining books with prices and metrics
Order books give you depth, but a complete market picture also needs price history and liquidity metrics. PolyOrderbooks serves these on separate endpoints with aligned timestamps, so you can join them in your analysis.
The /markets/{slug}/prices endpoint returns the midpoint price (average of best bid and best ask) at each timestamp. The /markets/{slug}/metrics endpoint returns derived liquidity metrics like total bid depth, total ask depth, spread, and volume-weighted average price.
By combining all three endpoints, you can reconstruct the full market microstructure: what traders saw (the book), what the price was (midpoint), and what the liquidity conditions were (metrics) at every second.
Common use cases
Order book data powers several distinct use cases. Backtesting is the most common: replaying historical books to test whether a trading strategy would have been profitable against real market microstructure. This includes fill simulation (would your order have been executed at your target price?) and slippage analysis (how much did the price move against you?).
Market microstructure research uses order books to study how prediction markets behave — how spreads evolve around resolution, how depth responds to news, and how different coins compare in terms of liquidity.
Liquidity analysis examines how much capital is resting on the book at various price levels, which is critical for understanding market quality and execution risk.
All of these use cases require the full L2 book, not just midpoints. A strategy that looks profitable on midpoint data may fail when you account for the actual depth available at your execution price.
Code examples
import requests
BASE = "https://api.polyorderbooks.com/v1"
HEADERS = {"X-API-Key": "your-key"}
slug = "btc-updown-5m-1787486400"
r = requests.get(
f"{BASE}/markets/{slug}/books",
headers=HEADERS,
params={"resolution": "1s"},
)
r.raise_for_status()
books = r.json()
# Analyze spread over time
for snap in books:
bid = snap["bids"][0]["price"] if snap["bids"] else None
ask = snap["asks"][0]["price"] if snap["asks"] else None
if bid and ask:
print(f"t={snap['timestamp']} spread={ask - bid:.4f}")Free tier
The Starter plan is free, includes order books, prices, and metrics at 1-second resolution, with 3 days of history, 60 requests/min, 1,000/day, 1 free AI backtest, and 3 strategy backtests. No credit card required.
Paid data windows from $19/mo extend history to 30–120 days at higher throughput. Backtest AI add-on is +$19/mo or standalone at $29/mo.
FAQ
What resolution does the order book API use?
1 second on every plan, including the free Starter tier. Paid plans also support coarser query grids from 60s to 1s. The capture cadence is uniform — you choose the grid at query time.
Does the API include resolved markets?
Yes. Resolved markets stay queryable with the winning outcome on every row. Prices and books for the full history are available after resolution — nothing is deleted.
What is in a book snapshot?
Full bid/ask ladders — every level, not just the top of book. Each row carries aligned bids, asks, spread, depth, and a timestamp. Prices and metrics come on separate endpoints with the same timestamps.
How does this differ from Polymarket's own /book endpoint?
Polymarket's CLOB /book endpoint serves the live order book at the current moment. PolyOrderbooks captures and stores the complete book state at regular intervals, so you can query the exact book that existed at any point in a market's history.
Can I get the full market lifecycle in one request?
Yes. Omit start_ts and end_ts to get the full lifecycle from market open to resolution. The response includes every 1-second snapshot, which for a 5-minute market is approximately 300 snapshots.
What is the maximum time range I can query?
The maximum range depends on your plan. Starter gives 3 days, paid plans give 30–120 days. Within that window, you can query any contiguous range. Large ranges return more data and count more against your daily limit.