Workflow
Polymarket price history vs order books
Polymarket's free CLOB /prices-history returns a per-token price series with no API key required. PolyOrderbooks /books returns full L2 order books at 1-second resolution. Here is when to use each, with code for both.
What this guide covers
- CLOB /prices-history is free, no API key required
- PolyOrderbooks /books returns full L2 ladders, not just midpoints
- Prices-history gives implied probability per outcome token
- Use PolyOrderbooks when you need depth, spread, or fill simulation
What Polymarket's free /prices-history gives you
Polymarket's CLOB API offers a free /prices-history endpoint that returns the price history for any outcome token. No API key is required — just pass the token ID and an interval.
The response is an array of {t, p} objects where t is a timestamp and p is the price (implied probability) at that moment. The interval parameter controls the sampling rate: '1m' for minute-level, '1h' for hourly, '1d' for daily.
This is useful for quick price charts, trend analysis, and implied probability tracking. It's the fastest way to get historical price data for a Polymarket market.
The main limitations: no order book depth (just the price), limited resolution (minute-level at best, hourly for older data), and no aligned metrics or spread data.
What PolyOrderbooks /books adds
PolyOrderbooks captures the complete L2 order book at 1-second resolution. This includes every bid and ask at every price level, not just the midpoint.
The key difference is depth. A price tells you where the market is; the order book tells you how much capital is resting at each level. This is critical for fill simulation — you can't estimate slippage from midpoint data alone.
PolyOrderbooks also provides aligned metrics (spread, total depth, volume-weighted average price) and prices with the same timestamps as the books. This means you can join all three datasets for a complete market picture.
| Feature | Polymarket /prices-history | PolyOrderbooks /books |
|---|---|---|
| API key required | No | Yes |
| Data type | Midpoint price | Full L2 book |
| Resolution | Minute-level (best) | 1-second |
| Order book depth | No | Yes (every level) |
| Spread data | No | Yes |
| Metrics | No | Yes (aligned timestamps) |
| Resolved markets | Limited | Full history |
| Rate limit | IP-based, undocumented | Per key, documented |
When to use each
Use Polymarket's free /prices-history when you need quick price charts or implied probability tracking. It's free, fast, and requires no setup. Perfect for dashboards, trend analysis, and simple visualizations.
Use PolyOrderbooks /books when you need order book depth for backtesting, fill simulation, slippage analysis, or microstructure research. The L2 data lets you simulate realistic execution against the actual book.
Many users start with /prices-history for quick exploration, then move to PolyOrderbooks when they need depth. The free Starter tier gives you 3 days of L2 history to test the difference.
For production applications that need reliable, documented rate limits and full historical access, PolyOrderbooks is the better choice. The per-key rate limits are predictable, and the data format is consistent across all endpoints.
Code examples
import requests
# Free — no API key needed
token_id = "0x..." # outcome token ID from the market
clob = requests.get(
"https://clob.polymarket.com/prices-history",
params={
"market": token_id,
"interval": "1m",
"fidelity": 1,
},
).json()
# clob is an array of {t, p} objects
for point in clob[:5]:
print(f"t={point['t']} price={point['p']}")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
Can I use Polymarket's free /prices-history instead?
For simple price charts and implied probabilities, yes — /prices-history is free and requires no API key. Use PolyOrderbooks when you need full L2 depth, spread, aligned metrics, or historical book snapshots for fill simulation.
What is the difference in resolution?
The CLOB /prices-history returns minute-level or sub-minute intervals at best, and older data may only be hourly. PolyOrderbooks captures at 1-second resolution and lets you query grids from 60s down to 1s.
Do I need both?
Many users start with /prices-history for quick price checks and move to PolyOrderbooks /books when they need depth for backtesting, slippage analysis, or microstructure research. The free Starter tier gives you 3 days to test the difference.
Is Polymarket's /prices-history reliable for backtesting?
It's reliable for price-level analysis, but it doesn't give you order book depth. For backtesting that includes fill simulation and slippage, you need the L2 data that only PolyOrderbooks provides.
Which is better for building a trading dashboard?
For a simple price chart, /prices-history is free and fast. For a dashboard that shows depth, spread, and liquidity metrics, PolyOrderbooks /books gives you all the data you need in one endpoint.