Polymarket order book data shows the resting liquidity behind a prediction-market price: which bids and asks were available, at what prices, in what sizes, and when they changed. That is far more useful for serious analysis than a candle or a single current price, because it lets you model execution, slippage, depth, and shifting market pressure instead of guessing at them.
The real decision is not whether you need Polymarket prices. It is which form of the data your task demands: a current snapshot for monitoring, a real-time stream for a live trading system, historical book updates for research and backtesting, or a normalized delivery layer that an application or AI agent can consume across Polymarket and other venues. This primer defines the data, explains how Polymarket structures markets and outcomes, separates snapshots from incremental updates, and gives decision criteria for choosing a delivery surface.
Table of contents
What Polymarket order book data actually contains
A Polymarket order book is the set of resting buy and sell orders for a single outcome token. For one outcome, bids are the buy orders traders are willing to pay, and asks are the sell orders traders are willing to accept. The best bid is the highest available bid, the best ask is the lowest available ask, and the spread is the gap between them. Depth is the quantity available across one or more price levels, and the midpoint is the average of the best bid and best ask when both sides exist.
Polymarket exposes book levels as price-and-size records that can include the asset ID, bids, asks, timestamp, minimum order size, tick size, and last trade price. Because a prediction-market price generally represents an outcome probability, a price of $0.63 reads as a market-implied probability of roughly 63 percent, before fees, spread, and liquidity are considered. That number is only an executable price if sufficient liquidity sits at or near the level. A clear treatment of bids, asks, spread, and depth is in our walkthrough of order book data for traders.
Why the book beats candles for execution modeling
Candles compress activity into open, high, low, close, and volume. That is adequate for broad visual analysis, but it hides the execution conditions that decide whether a strategy works. The book lets you answer questions candles cannot: could a strategy have actually filled at the quoted price, how much size was available before the price moved, was a change caused by a trade or by cancellations, and did the apparent edge exceed the spread and expected slippage?
Consider a backtest that assumes every signal trades at the midpoint. It may report attractive returns while ignoring that the strategy would have crossed the spread, consumed multiple ask levels, or failed to fill entirely. A book-aware backtest instead models a marketable buy against the ask side or a marketable sell against the bid side, so the reported edge survives contact with real liquidity.
Markets, outcomes, and tokens: the model that breaks joins
A common implementation error is treating a market question as though it were the tradable instrument. Polymarket organizes data hierarchically: an event can contain one or more markets, a market represents a tradable question, each market has YES and NO outcomes, and each outcome has its own token or asset ID. The order book is retrieved or streamed for that outcome ID, not for the question text. The official workflow is to discover the event, select the specific market, identify the YES or NO outcome, and then use its ID to access market data.
This matters most when joining historical data. A readable market slug is not a stable trading key. For reproducible research, retain the market identifier, outcome or asset identifier, market question, outcome label, timestamps, and settlement status alongside every book event. Skip that discipline and you risk silently mixing a YES book from one market with a NO book from another, which poisons any downstream result.
Snapshots versus incremental book updates
Polymarket order book data arrives in two broad forms, and the difference decides what you can model. A snapshot captures the available bid and ask levels at a point in time. It is useful for checking current liquidity, calculating spread and depth, monitoring a watchlist, initializing a local book, or validating a historical reconstruction. What a snapshot cannot do is explain how the book reached that state; it cannot reliably separate new orders from cancellations or executions that happened between observations.
An incremental update, or delta, describes a change: a level added, resized, or removed. Apply a sequence of updates to an initial snapshot and you reconstruct the book through time. Incremental data is the stronger format for event-driven strategies, queue and fill modeling, market-impact analysis, latency studies, order-flow research, and replayable backtests.
Polymarket's public market WebSocket provides order-book, price, trade, and market-lifecycle updates. Subscriptions use asset IDs, the connection begins with book information for subscribed assets, and clients must send an application-level PING every 10 seconds and process the corresponding PONG. A production consumer also has to handle disconnects, missed messages, duplicate handling, sequence or timestamp validation, and snapshot reinitialization after a gap. A stream that is merely connected is not necessarily a stream that is safely reconstructing the book.
What a research-grade dataset must preserve
For quantitative work, "historical order book data" has to mean more than a table of periodic prices. Before you trust a dataset, confirm it preserves the fields that make results interpretable and reproducible.
| Data element | Why it matters |
|---|---|
| Outcome or asset ID | Prevents mixing YES and NO books or different markets |
| Market and outcome metadata | Keeps results interpretable and supports settlement joins |
| Side, price, and size | Enables spread, depth, slippage, and probability analysis |
| Exchange and receive timestamps | Separate venue timing from ingestion delay and ordering |
| Event type and sequence field | Distinguish book changes, trades, and lifecycle; detect gaps |
| Tick size and minimum order size | Define valid prices and prevent unrealistic simulated orders |
| Settlement or status data | Stops trading signals after a market is closed or resolved |
Polymarket's market-detail and CLOB documentation identifies trading constraints such as tick size and minimum order size, and its market-detail API exposes the spread as the difference between best ask and best bid. When those constraints are missing from a historical file, your simulated orders can violate the venue's own rules without you noticing.
Choosing a delivery method for your workload
The right surface depends on whether the task is live decision-making, historical analysis, or agent interaction. The decision criterion is not "API versus file." It is whether the surface preserves enough information to reproduce the market's state, and whether it fits the workload.
| Requirement | Suitable surface | Main evaluation criteria |
|---|---|---|
| Current book lookup | REST API | Auth, rate limits, identifiers, response schema |
| Live bot or monitoring | WebSocket stream | Ordering, heartbeats, reconnects, latency |
| Large historical research | Bulk Parquet or CSV | Coverage, partitioning, timestamps, schema stability |
| Repeatable backtest | Historical event files | Full books, trades, lifecycle, execution assumptions |
| AI agent or assistant | MCP server | Structured schemas, permissions, reproducibility |
Use a REST API when you need targeted retrieval or application integration, and live streams when your system must react to new events as they arrive. Reach for bulk files when you need to scan substantial history repeatedly, and an MCP server when an AI agent needs controlled access to market-data tools rather than an engineer wiring every endpoint by hand. Polymarket itself provides a CLOB API and a public market WebSocket, which are useful when an application needs direct venue connectivity; a separate normalized delivery layer earns its place when you want consistent identifiers, timestamps, and field names across venues.
Risks that quietly corrupt backtests
Several failure modes do not throw errors; they just produce confidently wrong results. A snapshot is not a complete history: polling a book periodically misses short-lived liquidity, rapid cancellations, and intermediate executions, so it is not equivalent to capturing every update. Displayed liquidity is not guaranteed execution either; an order can be canceled, displaced, partially filled, or gone by the time a strategy acts, so a backtest should never assume all displayed size is executable.
YES and NO are related outcomes but are not identical instruments, so preserve the outcome ID and verify the contract terms before combining them. Market status also changes over time as markets open, pause, close, or resolve, which is why historical systems need lifecycle and settlement records to avoid evaluating a signal against a state that did not exist at the time.
Fees matter for small edges. Polymarket states that taker fees apply to certain markets and are applied at match time, and its published fee schedule varies by category, so a backtest should use the fee regime applicable to the market and historical period rather than a universal assumption. Finally, timestamp choice changes results: use exchange time for market chronology and receive time for latency and availability analysis, because they answer different questions. For the discovery and historical-join workflow in depth, see our guide to getting Polymarket market data and our Polymarket historical data guide.
How we deliver Polymarket order book data
AymarData is built for users who need tick-level prediction-market and crypto data rather than candle-only history. Our published Polymarket coverage records full order books and trades with both exchange and receive timestamps, under a common schema intended for analysis across sources. That coverage currently focuses on crypto Up/Down market families for BTC, ETH, SOL, and XRP at 5-minute, 15-minute, hourly, 4-hour, and daily windows, with history beginning June 1, 2025. That makes it especially relevant for researchers studying short-horizon prediction markets, repeated market creation, and the relationship between crypto spot or perpetual prices and Polymarket outcomes.
The starting point depends on the project. For historical strategy research, begin with the Polymarket dataset and bulk delivery; for live execution or monitoring, use sequenced WebSocket book deltas and trade prints; for application development, use the REST API and documented quickstart; and for AI-agent workflows, expose structured access through the MCP server. For cross-venue analysis, combine Polymarket data with Binance, Kalshi, or other supported datasets where the identifiers and timestamp conventions allow a defensible join with explicit time tolerances. The value of order book data is not a more detailed chart. It is the ability to test what was available, when, and whether a strategy could plausibly have traded it.
Frequently asked questions
What is Polymarket order book data?
It is a time-ordered record of bids, asks, prices, sizes, and related market events for Polymarket outcome tokens. It can be delivered as snapshots, incremental updates, or both.
Is Polymarket order book data the same as price data?
No. A price is a single point observation. An order book shows executable liquidity across multiple price levels and can reveal spread, depth, cancellations, and shifting market pressure.
Can I use Polymarket order book data for backtesting?
Yes, but the backtest should model spread, available size, partial fills, fees, timestamps, market status, and the gap between displayed liquidity and actual execution.
Does Polymarket provide real-time order book data?
Yes. Polymarket documents a public CLOB market WebSocket for order-book, price, and market-lifecycle updates, with subscriptions keyed on outcome or asset IDs and a 10-second application-level heartbeat.
What Polymarket data does AymarData currently publish?
We publish crypto Up/Down families for BTC, ETH, SOL, and XRP across 5-minute, 15-minute, hourly, 4-hour, and daily windows, with history beginning June 1, 2025, recording full order books and trades with exchange and receive timestamps.