Polymarket Official API vs a Historical Archive

• GET /book — the current order book for one token: bids, asks, last trade price, tick size. A snapshot, not history.
• POST /books — the same current-book payload for many tokens in one request.
• GET /prices-history — a historical price series for one market, with interval options (1m, 6h, 1h, 1d, 1w, max) and a fidelity parameter in minutes (default 1).
• Streaming and discovery via Gamma and the CLOB data feed, plus the Data API — v2 is live and v1 is documented for retirement on October 24, 2026.
• py-clob-client for execution and public reads; a documented MCP server for agent use.

There is no documented official endpoint for arbitrary historical full L2 depth. Python /prices-history returns outcome prices over time, and /book returns the book now — nobody can ask the official API what the bid ladder looked like at a specific past minute. The full-depth book is off-chain, so it has to be captured as it happens by someone who keeps it.

That is the entire reason archives exist. The official API answers where the price was; an archive answers what you could actually trade at, and at what size, at a past instant.

• Live prices and current depth — official API, free and rate-limited. No archive needed.
• Settlement-aware backtests of Up/Down strategies — a depth archive at sub-minute resolution; the final minute of a 5-minute market is where the trade actually happens.
• Execution and order placement — the official CLOB API is the only path. Data providers do not trade.
• Long-horizon research over many markets — price series from the official API at 1-minute+ fidelity, or an archive when depth enters the question.
• Reconstructing a specific past book — an archive (250ms, event-driven, or tick), or the official API cannot do it.

Run the two endpoints side by side on the same second and the division becomes concrete. The official /book returns the current ladder for one token — bids, asks, last trade, tick size — and the official prices-history returns a series of outcome prices, at one-minute fidelity by default. Neither returns the order book shape at an arbitrary past second: not the sizes, not both sides, not the sequence of a repricing.

Now replay the recorded final minute of a resolved 5-minute Up/Down market. An archive serves every 250ms frame of that minute: the floor hanging on the bound, the one-sided state, the exact second the executable price resets. That hour of frames is exactly the material that published settlement research (298 resolved contracts across the BTC corpus) is built from, and it simply does not exist in the official response set.

The official stack and the archive are not in competition — they are consecutive stages of one pipeline. Live reads hit /book and the CLOB stream; anything that needs to be reproduced later reads the archive. Most teams on this site run both: official for now, archive for afterwards.

The decision rule is three questions. Is the job about what is true right now? Official API, free, rate-limited, done. Is the job about what was tradable at a recorded instant — sides, sizes, the settlement minute? Archive, because no official endpoint records it. Is the job execution and order placement? The official CLOB API is the only path; data providers never trade for you.

For backtests the archive wins by definition: a strategy simulation needs the framestream as it actually was, including the empty executable side during a reprise. The official 1-minute price series is the right supplement for long-horizon charting, and the two sit together in the same script without a conflict.

The honest edge case is the official fidelity parameter: at its finest minute setting it still runs about 30x coarser than the archive's 250ms grid, and it carries only prices, not depth. If a study ever depends on what you could fill at a given second, that study belongs in the archive.

• Full provider matrix
• Crypto data
• Order book data
• Provider comparisons