Polymarket API Guide: Live Markets, WebSockets and Historical Research
Polymarket exposes strong current-market interfaces. The architectural decision is where the official live surface ends and a continuously recorded historical book begins.
The Polymarket developer surface covers market discovery, prices, trades and live CLOB order-book updates. Use official documentation for current endpoint definitions and venue behavior. For historical research, first decide whether a price series is enough or whether the strategy needs the bid/ask ladder that existed at each decision time; only a continuously captured archive can provide the latter after the live update has passed.
Map the task to the data surface
| Task | Data needed | Typical source |
|---|---|---|
| Discover current markets | Events, markets, outcomes and identifiers | Official Polymarket APIs |
| Monitor current liquidity | Live bids, asks, sizes and price changes | Official CLOB WebSocket |
| Plot a probability series | Historical outcome prices | Official price-history surface |
| Replay execution | Past full ladders with timestamps | Continuously recorded archive |
| Compare with spot | Book observations joined to an underlying reference | Normalized research provider |
Why identifiers and timestamps come first
A Polymarket integration crosses event, market, condition and token identifiers. Store those relationships with the raw source values instead of treating a human-readable title as a key. A title can change; an execution study must still join the same outcome token to the same recorded book.
Keep source timestamps and receive timestamps separately. The source time describes the venue event, while receive time describes when your system observed it. Collapsing them into one field makes latency and ordering errors impossible to audit.
What DepthFeed adds
DepthFeed records event-driven Polymarket CLOB updates, builds normalized full-book observations and serves them through the same REST and WebSocket shapes used for Kalshi. Historical rows include price and size ladders rather than only a single probability point.
That record supports depth-aware VWAP replay in the Backtest Lab, historical API queries and next-book execution audits for public wallet activity. Missing coverage remains explicit, and the archive does not claim to reproduce hidden liquidity, queue priority or a real order's market impact.
Integration checklist
- Use official Polymarket docs as the authority for current endpoints and trading rules.
- Persist event, condition and outcome-token identifiers together.
- Seed a complete book before applying incremental price changes.
- Keep source and receive timestamps instead of overwriting one with the other.
- Use price history for charts and full historical ladders for execution replay.
- Test gaps, reconnects and duplicate updates before trusting a backtest.
Key takeaways
- 01The official Polymarket API is the correct authority for current venue state.
- 02Live CLOB updates must be seeded and ordered to reconstruct a complete book.
- 03A historical probability series does not reveal past resting depth.
- 04DepthFeed adds recorded full ladders and one cross-venue research schema.
- 05Identifiers, timestamps and missing-data behavior should be designed before strategy logic.
Query a recorded Polymarket book and compare price-only history with depth-aware replay. Free Explorer tier, no card.
Open the API docsView pricing