How to Download Polymarket Historical Data

This guide shows how to download Polymarket historical data in practice: where the venue's own public endpoints stop, what a recorded Polymarket archive actually contains, and the five steps from finding a series to a folder of Parquet files on your disk. Everything below uses the CryptoStruct prediction-market archive, where Polymarket data is recorded live, contract by contract, and sold per UTC day. If you only want to know what a file looks like, the tick file format guide walks through one byte by byte.

What Polymarket publishes — and what it cannot give you back

Polymarket runs an on-chain central limit order book (CLOB) with public read endpoints. As far as the public docs go (check the current documentation before relying on any of this), those endpoints serve the current order book of a market, market and event metadata, and sampled price history per outcome token. That is enough to chart a market's probability over time or to look up how a question resolved.

What they generally do not give you is the past order book: once a market has settled, its full Level-2 path — every quote placed, resized and cancelled, with the exact sequence in which trades hit the book — is not reconstructable from a sampled price series. Venue APIs can backfill some market, trade and price data, but the tick-by-tick book has to be recorded live at the time. For a 5-minute BTC up/down market that exists for minutes and is replaced by the next one, "start recording today" means you have today, not last year. This is the gap the archive fills.

What you can download: one file per contract, per UTC day

The archive records every open Polymarket contract as its own instrument, one file per UTC day: tick-by-tick trades plus the complete Level-2 order-book evolution (snapshots and incremental updates), with both the venue timestamp and the co-located capture timestamp in integer nanoseconds. Prices are USDC-quoted probabilities in 0..1; in the sample files the recorded tick size is 0.001 (tick sizes are market-specific and may change over time). There is no separate top-of-book (BBO) stream on Polymarket — the best bid and ask at any instant come from replaying the book, which the free reader does for you.

Contracts are grouped into series by their market slug (btc-updown-5m-…, for example); a Polymarket series is matched on that slug, not on a ticker prefix. As of 2026-09 the registry holds 241 Polymarket series across crypto, sports, politics, climate and culture. Files are small — about 353 KB compressed on average — which is why the unit of sale is the series-day bundle: every contract file of one series for one UTC day, from €1. The BTC 15-minute series has been recorded since October 2025 and the BTC 5-minute series since February 2026; every series page states its own first day.

Step 1 — find the series

Start from the prediction-market hub: the topic hubs group series by subject (Bitcoin up or down, soccer leagues, temperatures), the category pages list everything, and the most-traded leaderboard ranks series by 30-day trades and USD turnover from our own capture. Every series page shows its coverage span, a 30-day statistics table and the contracts of recent days, so you can check that the days you need exist before buying anything. Agents can do the same through the MCP server with search_bundles and get_bundle_coverage.

Step 2 — download the free sample contract

Each series page offers one free contract file — the busiest contract of a settled day about a week back — in the exact shop format, with the same CSV/Parquet export menu and a browser replay of its order book. Download it first and run the free reader against it: if your pipeline handles the sample, it handles every purchased file. The curated downloads page adds a Polymarket BTC 5-minute contract next to spot, perpetual and option samples.

# counts per message type, time span, chain gaps
python3 cryptostruct_reader.py stats polymarket-btc-updown-5m-…-2026-09-05.txt.zst --deep

# trades as a table, book sampled every second
python3 cryptostruct_reader.py trades FILE --out trades.parquet
python3 cryptostruct_reader.py book FILE --every 1s --depth 20 --out book_1s.parquet

Step 3 — buy the days you need

Open the series in the shop — for example Polymarket BTC 5m — and pick days in the calendar. One day of one series is one item at the series price (from €1), regardless of how many contract files it contains. Checkout is by card with an invoice, or with Premium credits; the download links appear immediately after payment and stay in your account. There is no subscription and no minimum: a single day of a single series is a valid order.

Step 4 — bulk download: one request per day, never per contract

A series-day can hold hundreds of contract files. Never fetch them one at a time: the order download URL streams the whole day as one ZIP, and the range endpoint streams every owned day of a window as one uncompressed tar. The tar is strict — exact content length, strong ETag, resumable with curl -C - — and covers up to 100 days per stream. Days older than about a month live in deep-archive storage: request a restore once, wait roughly twelve hours, then download; a cold day answers 409 instead of a short archive when you ask for a complete delivery.

# one series-day as a single ZIP; complete=1 refuses a partial day instead of shipping it short
curl -fL -o polymarket-btc-5m-2026-09-05.zip \
  "https://cryptostruct.com/api/download/order/{order}/{bundle}/2026-09-05?kind=series_day&zip=1&complete=1&t=$TOKEN"

# a whole date range as one resumable tar (≤ 100 days per stream)
curl -fL -C - -o polymarket-btc-5m-2026-08.tar \
  "https://cryptostruct.com/api/download/order/{order}/{bundle}/range?kind=series_day&from=2026-08-01&to=2026-08-31&t=$TOKEN"

# readiness first: pull once cold == 0
curl -s "https://cryptostruct.com/api/download/order/{order}/{bundle}/range?kind=series_day&from=2026-08-01&to=2026-08-31&status=1&t=$TOKEN"

Coding agents can run the same flow without a browser: the MCP server exposes search, coverage, quote, checkout and file listing as tools, and the order files come back with zip and status URLs per day.

search_bundles      {q: "btc 5m", venue: "polymarket"}      → bundle_id, series_key polymarket-btc-5m
get_bundle_sample   {series_key: "polymarket-btc-5m"}        → download_url of the free contract file
get_bundle_coverage {series_key: "polymarket-btc-5m"}        → days[] with file_count / total_bytes / price_eur
get_price_quote     {items: [{instrument_id, date, kind: "series_day"}, …]}
create_checkout     {email, items: [… same items …]}         → checkout_url (or, signed in, paid)
get_checkout_status {session_id | order_id}                  → order_id + download_token
get_order_files     {order_id, download_token}               → per day: zip_url, status_url, restore_url

Step 5 — CSV, Parquet or the native tick files

Every sample and every purchased file serves flat exports via ?format= on its download link: trades.csv.gz and trades.parquet with microsecond UTC timestamps and columns per the docs convention. Because Polymarket carries no BBO stream, there is no BBO export for these files — run the free reader's book command instead, which replays the L2 book and writes top-of-book or full depth on any time grid. The native files keep nanosecond timestamps and decimal-string prices; turnover in the analytics is USD-normalized even though the contracts quote in USDC.

unzip -q polymarket-btc-5m-2026-09-05.zip -d bundle/2026-09-05
for f in bundle/2026-09-05/*.txt.zst; do
  out="parquet/$(basename "$f" .txt.zst).parquet"
  [ -f "$out" ] || python3 cryptostruct_reader.py trades "$f" --out "$out"
done
# python: pl.scan_parquet("parquet/*.parquet") — one frame across all contracts

Backtesting notes specific to Polymarket files

• Anchor on the contract window, not the file. A Polymarket 15-minute market's book streams for many hours around its window, so a day file contains long stretches before and after the minutes that matter; slice by the window's start and end, as the Kalshi vs Polymarket comparison does.
• Consecutive day files overlap by design — roughly eight minutes of the previous day and one minute of the next — so trim each file to its nominal UTC window or deduplicate on event id before stitching days.
• The outcome implied by the last print (close at or above 0.97 for Yes/Up, at or below 0.03 for No/Down) is a data heuristic, not the official resolution. Derive labels from the venue's resolution metadata when you train on settlement.
• Prices are decimal strings on purpose; cast to float for features, keep decimals for anything that adds up money.
• Replay the book per file from its first snapshot; never concatenate raw event streams across files.

What you can buy today

Limitations

The description of Polymarket's own endpoints is deliberately general: it reflects what the public documentation described when this guide was written, and the venue can change it at any time — check the current docs before building on it. Archive coverage starts at each series' first recorded day and is not complete for every Polymarket market that has ever existed; the series pages show exactly which days exist. Recording gaps happen on outage days and are visible in the per-day statistics. Tick sizes and sizes quoted here come from 2026 sample files. Not investment advice; this is a data access guide.