How to Get Historical Polymarket Order Book Data for Backtesting

If you are building a strategy on Polymarket, you eventually need more than the current quote. Live APIs expose what the book looks like right now. Backtests need what it looked like then — repeatedly, at known timestamps, for every outcome in a market.

That gap is harder than it sounds. Order books are ephemeral. Unless you capture and store snapshots yourself, the depth that was available before a news event or resolution is gone. This article explains why that matters, what historical L2 data unlocks, and how to pull a time series with Python.

The problem

Polymarket provides live order books and historical price data, but its public APIs do not offer a first-class archive for retrieving full historical L2 bid-and-ask ladders at arbitrary past timestamps. You can read current depth and place orders through the CLOB, but there is no documented "give me the full ladder from last Tuesday" endpoint on the public trading surface.

Researchers and builders who want historical depth typically face three unattractive options:

• Record it yourself — run collectors 24/7, normalize token ids, handle reconnects, and store terabytes of deltas.
• Proxy with trades or mid prices — faster to wire up, but you lose information about size at each level and whether your size could have traded.
• Use a third-party archive — someone else has already paid the storage and ingestion cost; you query snapshots over HTTP.

The third path is what most teams want once they are serious about simulation. The hard part is finding a source that stores L2 ladders (price and size per level), not just last trade or midpoint.

Why trade history isn't enough

Trade prints answer "what traded?" They do not fully answer "what could I have traded, and at what cost?"

Spread. The gap between best bid and best ask changes through the day. A backtest that fills at the mid price assumes you capture half the spread on every entry and exit — optimistic for any strategy that crosses the book.

Liquidity. A level might show a tight quote with only $50 of size. Your model might assume a $5,000 fill at that price because the mid moved there once. Order-book snapshots show cumulative depth so you can cap fills by available size.

Slippage. Walking the ask (or bid) to complete a larger order produces worse average prices than the top of book. You need the ladder — multiple price levels with sizes — to estimate impact.

Realistic fills. Many strategies only work if you can model limit-order placement: join the bid, get hit when flow arrives, or never fill when the market moves away. That requires book state, not just a price chart.

Mid prices and volume bars are fine for exploratory charts. They are a weak foundation for execution research on prediction markets, where spreads are wide relative to equities and liquidity is concentrated around a few levels.

What historical order-book data enables

Once you have timestamped L2 snapshots per outcome token, several classes of analysis become straightforward:

• Backtesting — replay decisions on the book state at decision time; apply fill rules that respect depth and spread.
• Liquidity analysis — measure how much size sat within 1¢, 2¢, or 5¢ of the mid over hours or days; compare events or market types.
• Market microstructure research — study how books thin before resolution, how informed flow shows up on one side, or how crypto-linked markets behave around macro prints.
• Execution simulation — test TWAP/VWAP-style logic, queue position heuristics, or "would this limit have filled?" without risking capital.

The common thread is path dependency: outcomes depend on the sequence of book states, not a single summary statistic per candle.

A Python example using a historical archive API

The workflow below uses a read-only HTTP API that serves stored snapshots (no live Polymarket calls on the read path). You will need an API key from the provider's signup flow; set POLYORDERBOOKS_API_KEY in your environment.

1. Discover a market slug with GET /v1/markets.
2. Request books with GET /v1/markets/{slug}/books, passing start_ts, end_ts, and resolution (e.g. 60s on free tiers, 1s on paid plans).
3. Parse each bucket's b (bids) and a (asks) as [price, size] ladders keyed by outcome label. PolyOrderbooks returns both ladders best-price first (bids descending, asks ascending).

import os
from datetime import datetime, timedelta, timezone

import requests

BASE = "https://api.polyorderbooks.com"
API_KEY = os.environ["POLYORDERBOOKS_API_KEY"]
HEADERS = {"X-API-Key": API_KEY}

# 1. Find a market to study
markets = requests.get(
    f"{BASE}/v1/markets",
    params={"search": "bitcoin", "limit": 5, "status": "active"},
    headers=HEADERS,
    timeout=60,
)
markets.raise_for_status()
slug = markets.json()["data"][0]["slug"]

# 2. Pull historical L2 books (60s buckets on Starter)
end = datetime.now(timezone.utc)
start = end - timedelta(hours=6)

books = requests.get(
    f"{BASE}/v1/markets/{slug}/books",
    params={
        "start_ts": start.isoformat().replace("+00:00", "Z"),
        "end_ts": end.isoformat().replace("+00:00", "Z"),
        "resolution": "60s",
        "limit": 100,
    },
    headers=HEADERS,
    timeout=120,
)
books.raise_for_status()
payload = books.json()

for outcome, points in list(payload["data"].items())[:2]:
    for point in points[:2]:
        bids = point.get("b") or []
        asks = point.get("a") or []
        best_bid = bids[0][0] if bids else None
        best_ask = asks[0][0] if asks else None
        print(point["t"], outcome, "bid", best_bid, "ask", best_ask)

Paginate with metadata.next_cursor if your window returns more than one page. For single-token depth on wide markets, use /v1/tokens/{token_id}/books. Pair book pulls with /prices or /metrics on the same window if you need volume or spread time series alongside ladders.

Full parameter reference and response shapes are in the quickstart and historical order book docs.

Conclusion

Historical Polymarket research needs archived order books, not just prices that traded. Spreads, depth, and ladder shape determine whether a strategy is tradable at all. Recording that data yourself is possible but operationally heavy; an archive API lets you spend time on simulation logic instead of ingestion.

Start with a narrow question — liquidity around resolution, or fill quality for a fixed size — pull one market's /books window, and validate your assumptions on real depth before scaling up. The PolyOrderbooks documentation covers authentication, resolutions, and pagination; a free tier is enough to prototype on recent crypto markets.

---

Originally published at polyorderbooks.com.