For a Polymarket backtest, distinguish price history and executed trades from recorded resting book states. A price series alone cannot show how much size was available at a past quote. This guide explains source options and the schema checks needed before treating an archive as an execution replay.
What the Polymarket API actually gives you
Polymarket's CLOB API is genuinely good for live trading. What it returns:
- The current order book —
GET /bookgives you the live bid/ask ladder right now. - Trade history — the prints that executed, with price and size.
- Historical prices — the
/prices-historyendpoint returns a price series; Polymarket documents requested accuracy (fidelity) in minutes, with a default of one minute. It is not a historical depth or execution replay. See the official parameter reference.
What it does not return:
- The order book as it was at 7:14 PM in the third quarter — the depth, the sizes at each level, the spread — at an arbitrary past moment.
This is the same gap on Kalshi: the API exposes current depth and trades, not a historical depth archive. (We cover the broader landscape in our complete guide to prediction market APIs and the practical Polymarket API guide.)
Why you can't just backfill it
Executed trades do not identify every unexecuted resting order. Reconstructing a ladder needs recorded snapshots or a sufficiently complete, time-ordered update stream with a valid initial state. If a provider already recorded it, you may obtain that history later; absence from your own recorder is not proof that nobody has it. Check current official endpoints and third-party archives for the exact period and granularity you need.
Your source options
1. Record it yourself, going forward. Stand up a websocket client against both venues, snapshot the book on every update, and store it. This works — it's exactly how the data gets created — but it has two costs: you get zero history before the day you start, and capturing clean, gap-free, multi-venue depth at scale (with reconnection handling and clock discipline) is more engineering than it first appears.
2. Use historical prices. This is simpler than recording a book, but prices alone do not tell you the spread or size available for a hypothetical fill. Do not assume a price-series observation is an executable bid or ask.
3. Inspect a free recorded archive. PMXT offers recorded Polymarket and Kalshi files, and Marketlens publishes selected Polymarket books, trades and outcomes. Neither listing proves that your particular market/window is complete.
4. Buy a recorded archive. Evaluate its specific schema, observed coverage, clocks and license against those free options. A provider’s advertised row count is not evidence of full exchange or season coverage.
Match the archive to the research question
Check the fields in the specific product schema before choosing an archive:
- Price and size detail. Top-of-book quotes, depth aggregates and per-level L2 rows support different questions. Recorded levels can constrain a hypothetical order-walk model, but do not prove fills or queue position.
- Venue and time alignment. Independent venue files require a verified market mapping and an explicit time tolerance. A paired product can still use a later quote within its stated tolerance; use a prior-only rule if the study must avoid look-ahead.
- Sports context. Verify which table contains game state and whether it belongs to observation or retrieval time. A capture-time score is not an independently verified sporting event timestamp.
A quote midpoint is a recorded price calculation, not a fill. Missing observations are not unchanged quotes.
A concrete example
Start with the free Kalshi-side CSV. Inspect its actual columns and a few rows in DuckDB:
DESCRIBE SELECT * FROM read_csv_auto('orderbook_archive_sample.csv');
SELECT * FROM read_csv_auto('orderbook_archive_sample.csv') LIMIT 5;
The free CSV and paid Parquet files have distinct contracts; check each schema and price unit before comparing values. The paid legacy archive schema defines Kalshi prices in cents and Polymarket prices in 0–1 dollars. For the paid Kalshi file, this query makes the unit conversion explicit:
SELECT datetime_utc, period, time_remaining, home_score, away_score,
yes_bid / 100.0 AS bid_dollars,
yes_ask / 100.0 AS ask_dollars,
mid / 100.0 AS midpoint_dollars
FROM 'kalshi_snapshots.parquet'
ORDER BY datetime_utc;
Game state in the paid archive belongs only to Kalshi and reflects capture time. The Polymarket table has no score or game-clock fields and is not pre-keyed to Kalshi. Inspect recorded quotes alongside that observed context; these files alone cannot establish a sporting event time, a score-response delay or an executable trading edge. Event-time work needs a separately verified timeline.
Where to get it
We publish distinct archive contracts rather than one interchangeable data feed:
- Polymarket sports quotes and L2-depth archive — recorded top quotes and separate per-level depth files, with dated coverage and gaps. L2 capture starts Jun 16, 2026; there are no trade prints, and selected markets are not a census.
- $9 Polymarket sports archive tryout — the Sep 6–7, 2026 slice for testing the same file layout and schema before buying more coverage.
- $150 legacy Polymarket and Kalshi book archive — two independent venue tables: Kalshi Dec 28, 2025–Jan 30, 2026 and Polymarket Jan 18–29, 2026. Polymarket has top quotes and depth aggregates; Kalshi has top-of-book quotes with capture-time game state. There is no shared venue key or per-level ladder in this archive.
- Kalshi historical L2 depth and captured trade tape — sampled depth up to 20 levels per side, plus captured prints with separate exchange and retrieval clocks. Game context on prints belongs to retrieval time.
- Cross-venue top-of-book archive — separate venue files with recorded best quotes, without L2 depth or a pre-keyed shared timeline.
- Prediction-market microstructure dataset — derived quote-freeze, recovery and related analysis tables with their own methods and limits.
Start with the free Polymarket sports CSV and its schema and capture limits. If the fields suit your analysis, test your pipeline on the $9 two-day tryout before choosing the $149 larger archive. The free CSV is a sample, not the complete paid tryout.
For other datasets, browse the samples and schemas and all data archives. Confirm the fields, price units, observed window, mapping requirements and gaps for the artifact you intend to buy. Our historical-data buyer's guide compares source options.
Historical book observations must have been captured when the book was visible. That does not make the archive complete or every other data type non-backfillable: inspect the specific capture and its limits.