Polymarket order book snapshots
Polymarket order book snapshots: what a 250ms L2 capture contains
A Polymarket order book snapshot is the full bid and ask ladder at one instant: price levels with sizes, a captured_at timestamp, and flags for [crossed](/polymarket-order-book-data) or one-sided books. PolyOrderbooks stores one every 250ms — four per second, roughly 1,200 per 5-minute market.
Figures measured as of 2026-10-02 on the published PolyOrderbooks archive.
Short answer
A recorded state, not a delta
A snapshot records the book whole at a moment in time: the complete bid and ask ladders, sorted best-first, each level with a price on the 0–1 probability scale and a size in shares. Because it is a full record rather than a change event, it never needs reconstruction.[[Reconstruction diverges]] — replay against the archive's own snapshots diverged at 67.8% of 381,093 checkpoints.
Snapshots are captured every 250ms while a market is open — four full ladders per second — and a 5-minute market is roughly 1,200 snapshots from open to resolution. Omit start and end timestamps on the books endpoint to get the whole lifecycle.
Schema
The fields in a snapshot
| Two tokens per market | A binary market has an Up token and a Down token, each with its own book. They are separate order books, not two sides of one. |
|---|---|
| Prices are probabilities | Every level sits in [0, 1]. A bid of 0.19 is someone offering 19 cents for a contract that pays 1.00 if that outcome wins. |
| Sizes are share counts | Multiply by price for the dollar value resting at that level. |
| Ladders are best-price first | Bids descend from the highest, asks ascend from the lowest. |
| Depth varies per snapshot | Median 39 bid levels on 5-minute markets, but it ranges from zero to over 120. Never assume a fixed number. |
Quality
Flags are data, not defects
On the published 5-minute books, 16.9% of snapshots are one-sided and 3.24% are crossed — best bid above best ask, which cannot happen in a live matching engine because those orders would fill. Crossed rows last a median 2 seconds and 98.2% of episodes clear within 60 seconds.
Rows are kept and flagged with a crossed marker rather than removed, so the rate stays measurable by anyone, not just us. In the final minute before resolution, 76.2% of snapshots have an empty bid or ask side — nobody offers the losing outcome.
Get it
Where to get them
- REST API — /v1/markets/{slug}/books returns snapshots at 250ms-to-1d resolution; free Starter with 3 days of history.
- Free BTC sample — one market open to settlement, CSV or JSON, no signup.
- Open dataset — 897,192 snapshots across 805 resolved markets on Zenodo, CC BY 4.0, 43 MB as Parquet.
- Size note — a 5-minute market at 250ms is roughly 600 KB of JSON; columnar formats handle scale (formats guide).
Worked example
The same idea through the record
A snapshot is the book at one recorded instant: every price level with its size on both sides, a captured_at timestamp, and flags marking states like crossed. It is a state, not a delta — the archive stores it whole, four times per second, so a query for any past second returns the entire ladder as it stood.
The texture of a real snapshot is genuinely odd versus central-limit intuition: levels bunch at round boundaries (0.99, 0.995), sides vanish near settlement, and the executable price is the floor, not the average of the two quote streams. Reading one frame shows all of it at once.
Flags are data rather than defects: a crossed flag on a snapshot says the book momentarily had the bid above the ask, and in the replay experiment 6.4% of reconstructed books came back crossed — which is exactly why a stored frame referencing its own state matters more than a silently "cleaned" view.
A first pull is one hour of one market: open the raw rows, count the levels, find the rows where a side emptied, and watch the executable price migrate to the bound. Nothing else in the catalogue teaches the venue as fast as that one afternoon of frames.
Signals
What to check before you trust it
Verify snapshot cadence in the dataset header before analysis: on every plan the capture is 250ms, and studies claiming finer or coarser resolution need to say how they know.
Treat crossed states as a measurement of the market, not an error in the file; their frequency is part of the microstructure, and the archive preserves it rather than editing it away.
Reconcile your own first snapshot manually: read the levels, sum depth, confirm the timestamp — one manual frame grounds every later aggregate.
When comparing books across providers, demand frames of the same second; two archives can both be "250ms" and still disagree on what a reprise looked like.
FAQ
What fields does a Polymarket order book snapshot contain?
A full bid and ask ladder — price levels sorted best-first with sizes in shares — plus a captured_at timestamp and resolution metadata including the winning outcome. Rows carry a crossed flag where the best bid is at or above the best ask.
How often are snapshots captured?
Every 250ms while a market is open — four complete ladders per second — giving roughly 1,200 snapshots for a 5-minute market from open to resolution. Queries run from 1 day down to 250ms on every plan.
Why do snapshots have crossed or one-sided rows?
They are genuine market behavior at the capture instant. On 5-minute books, 16.9% of snapshots are one-sided and 3.24% crossed; crossed episodes last a median 2 seconds and 98.2% clear within 60 seconds. Rows stay flagged, not filtered, so the rate stays measurable.
Can I inspect snapshots before paying?
Yes. A single BTC 5-minute market from open to settlement is free in CSV or JSON with no signup, and 897,192 snapshots across 805 resolved markets are published on Zenodo under CC BY 4.0.