DEV Community: PolyOrderbooks

Polymarket Price History: How to Download Historical Prices with Python

PolyOrderbooks — Sun, 09 Aug 2026 16:41:38 +0000

If you want Polymarket price history in a notebook or CSV, you do not need a paid data vendor to get started. Polymarket documents a public /prices-history endpoint on the CLOB API — no API key, no signup. This article shows how to download Polymarket historical prices with Python using that official path first, then when a hosted archive is worth considering.

That order matters. Many researchers only need implied-probability time series for charts or signal work. Others eventually need unified Polymarket price data alongside metrics or historical L2 depth. We will cover both — without skipping the free option.

What Polymarket price history actually is

Each Polymarket outcome trades as a token on the CLOB. Historical prices are stored per token ID (the asset id in Polymarket's docs), not per market slug. A binary market has two series — typically YES and NO — and each point is a timestamp t plus an implied probability p between 0 and 1.

This is Polymarket price data suited to time-series analysis: repricing before events, correlation across markets, coarse backtests. It is not the same as an archived order book — you get a price line, not bid/ask ladders with size at each level.

Step 1: resolve token IDs with the Gamma API

The CLOB /prices-history endpoint requires a token ID. The Gamma API exposes market metadata, including clobTokenIds — a JSON-encoded array of outcome token IDs for each market.

Typical flow: search or list markets on Gamma, pick one, parse clobTokenIds, then pass the YES (or NO) token id to /prices-history. Polymarket's prices and order books docs walk through the same pattern in more detail.

Step 2: download history from Polymarket's CLOB API

The documented endpoint is GET https://clob.polymarket.com/prices-history. Important parameters:

market (required) — outcome token ID.
interval — relative window such as 1h, 1d, 1w, or max. Mutually exclusive with an absolute range.
startTs / endTs — Unix timestamps for a fixed window (use these when you need a specific date range).
fidelity — sampling interval in minutes (default 1). Higher fidelity means more points.

The response shape is {"history": [{"t": ..., "p": ...}, ...]}. Public access — Polymarket applies IP-based rate limits and throttling, so pace bulk downloads and design for backoff rather than hammering the API.

Python example: official Polymarket price history

This script uses only Polymarket's public Gamma + CLOB APIs. Install requests if you need it (pip install requests).

import json
import time
from datetime import datetime, timezone

import requests

GAMMA = "https://gamma-api.polymarket.com"
CLOB = "https://clob.polymarket.com"

# 1. Resolve a market and its outcome token IDs (Gamma — public, no API key)
markets = requests.get(
    f"{GAMMA}/markets",
    params={"limit": 5, "active": True, "closed": False},
    timeout=60,
)
markets.raise_for_status()
market = markets.json()[0]
token_ids = json.loads(market["clobTokenIds"])
yes_token_id = token_ids[0]

print(market["question"])
print("YES token:", yes_token_id[:12], "...")

# 2. Pull Polymarket price history (CLOB /prices-history — public, no API key)
history = requests.get(
    f"{CLOB}/prices-history",
    params={
        "market": yes_token_id,
        "interval": "1w",   # or use startTs + endTs for an absolute window
        "fidelity": 60,     # minutes between points
    },
    timeout=60,
)
history.raise_for_status()
points = history.json().get("history", [])

for point in points[:5]:
    ts = datetime.fromtimestamp(point["t"], tz=timezone.utc).isoformat()
    print(ts, "implied prob", point["p"])

# 3. Export to CSV (polymarket price data download)
# with open("prices.csv", "w") as f:
#     f.write("timestamp,price\n")
#     for point in points:
#         f.write(f"{point['t']},{point['p']}\n")

time.sleep(0.2)  # pace yourself — IP-based rate limits apply

Practical tips:

For long windows at fine fidelity, chunk with startTs / endTs instead of relying on interval=max alone — community reports suggest very fine granularity on resolved markets can return sparse data unless you bound the range explicitly.
Loop one request per outcome token (YES and NO) if you need both sides.
Add a short sleep between markets when downloading many series — respect documented rate limits.

When the official API is enough

Stay on Polymarket's /prices-history when:

You are exploring one market or a small set of markets.
You need implied probability over time, not full book depth.
You are fine resolving token IDs through Gamma yourself.
Hourly or daily fidelity is sufficient for the question.

For many charting and research tasks, that is the right stopping point — and it costs nothing beyond your time.

When a historical archive helps

A third-party archive (or your own recorder) becomes useful when Polymarket historical data needs to look like a product API rather than a script that stitches Gamma + CLOB:

Unified queries — discover markets by slug and pull /prices, /metrics, or /books on the same start_ts / end_ts window without token-id plumbing each time.
Both outcomes in one response — archive APIs often key price series by outcome label (YES / NO) for a market slug.
Historical L2 order books — if price history stops being enough and you need bid/ask ladders, see How to Get Historical Polymarket Order Book Data for Backtesting.
Bulk polymarket data download — warehouse exports (Parquet, CSV) or scheduled pulls across hundreds of markets.

For the broader map of prices vs trades vs books vs API access, see Polymarket Historical Data: Prices, Trades, Order Books, and API Access.

Optional: same window through an archive API

If you already use a hosted historical API, the shape is similar — market discovery, then a prices route — but keyed by slug and paginated. Example with PolyOrderbooks (requires a free API key from the dashboard):

import os
from datetime import datetime, timedelta, timezone

import requests

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

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

end = datetime.now(timezone.utc)
start = end - timedelta(days=7)

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

for outcome, series in prices.json()["data"].items():
    print(outcome, len(series), "points")

This is optional. Start with Polymarket's official endpoint; move here when unified history, metrics, or book depth justify it. Docs: quickstart and historical overview.

Summary

Polymarket price history is available today through documented public APIs: resolve token IDs on Gamma, call /prices-history on the CLOB, export the series. That covers a large share of polymarket historical prices and polymarket price data use cases with no vendor lock-in.

Reach for an archive when you need one interface for prices, metrics, and stored L2 books — or when IP limits and multi-market orchestration become the bottleneck. Either way, you are downloading real market history, not guessing from live quotes alone.

Originally published on PolyOrderbooks.

Polymarket Historical Data: Prices, Trades, Order Books, and API Access

PolyOrderbooks — Fri, 07 Aug 2026 09:58:41 +0000

If you are researching Polymarket, the first practical question is usually where to find Polymarket historical data — prices, trades, and order books — and how to download it for analysis. The answer depends on what you are building. Charting how a market repriced last month is a different problem than simulating whether a $2,000 order would have filled against the bid stack.

This guide walks through what Polymarket exposes on its own, what you need an archive for, when price history is enough, when full book depth is required — and a short Python example to pull a time series.

What Polymarket provides directly

Polymarket splits public data across a few surfaces. None of them is a complete historical archive for every research use case, but each covers part of the picture:

Historical prices — Polymarket exposes historical price-series endpoints, including batch price history. These are useful for probability and time-series analysis, but they are not equivalent to archived L2 order-book snapshots.
Gamma API — discovery and metadata: events, markets, tags, current outcomes, volume, and liquidity fields useful for browsing. Good for finding what exists and what is active today.
CLOB API — trading and live market structure: placing and canceling orders, recent trade activity, and the documented order-book endpoint, which returns the current book for a token. Real-time book updates stream over the WebSocket; neither replaces a historical L2 archive.
On-chain settlement — outcome resolution and token mechanics live on Polygon. That layer confirms final states; it is not a convenient historical prices API.

If you are looking for a Polymarket order book API, the official CLOB API gives you the current book, while a historical archive is needed for past L2 snapshots.

In practice, teams that only call Polymarket directly can answer "what is the market quoting right now?" and "what traded recently?" Polymarket provides historical price-series endpoints, but researchers still need a separate archive if they want to replay full historical L2 bid/ask ladders at arbitrary past timestamps.

Is the Polymarket API free? Rate limits and what you actually get

Developers often ask is Polymarket API free. Polymarket provides public API access to market metadata, historical prices, and live market data. Usage is subject to documented rate limits, and this access is not the same as a historical L2 archive.

Polymarket API rate limits still apply. Polymarket applies IP-based rate limits and throttling across its APIs, so high-volume collectors need to respect the documented limits and design for backoff and pacing. Those constraints are aimed at live apps and market makers, not unattended bulk backfills across thousands of markets.

The documented order-book endpoint returns the current book for a token; the WebSocket streams real-time updates. Neither offers a way to page through archived L2 depth from six months ago. For stored snapshots, you either run your own recorder or query a hosted historical API with /books and /prices routes.

What requires an archive

An archive (your own pipeline or a hosted historical API) stores snapshots over time so you can query the past on demand. You typically need one when:

You want prices, metrics, and books from one queryable archive — consistent schemas and pagination — without stitching separate Polymarket endpoints or pacing around IP limits.
You need historical order book data — multiple price levels with size, not just the last print or a single mid.
You are backtesting across many markets and want consistent schemas, pagination, and API keys instead of ad-hoc CSV dumps.
You want bulk export for a warehouse (some providers also offer Enterprise S3 drops in Parquet, CSV, or JSON).

Recording everything yourself is possible: websocket feeds, token-id normalization, deduplication, and cold storage add up fast. Most research teams eventually buy time back by querying someone else's store.

Prices, trades, and order books — three different downloads

These terms get used interchangeably in search, but they answer different questions:

Prices — time series of implied probability (per outcome token), usually derived from the top of book or last trade. Lightweight, ideal for charts, correlation studies, and coarse signal research.
Trades — discrete prints: size, price, side, timestamp. Answers "what actually exchanged hands?" Useful for volume profiles and trade-based backtests, but incomplete for limit-order strategies that might never have traded.
Order books (L2) — bid and ask ladders: price and size at each level. Answers "what was available to hit or join?" Required when spread, depth, and queue position matter.

A hosted archive API often exposes all three (or prices + books + derived metrics) over the same start_ts / end_ts window so you can align series in one notebook.

When prices and trades are enough

Start with price history when your question is about direction or level, not execution quality:

Plotting how a market repriced before an election, macro print, or sports result.
Comparing implied probabilities across related markets.
Training models where fills are assumed at mid or at last trade (know the limitation).
Screening hundreds of markets for volatility or drift without per-market book storage.

Trade history extends that when you care about observed activity — how much size cleared and at which prices — but you are still okay ignoring orders that rested on the book without filling.

When you need order book depth

Move to full L2 ladders — Polymarket order book data with size at each level — when assumptions about liquidity stop being harmless:

Estimating slippage for sizes larger than the top of book.
Modeling limit orders that join the bid and may or may not fill.
Measuring spread and depth over time, not just midpoint.
Serious backtests where "fill at mid" would overstate edge.

For a deeper walkthrough of that gap — why mids and prints are not enough — see How to Get Historical Polymarket Order Book Data for Backtesting.

Python example: pull historical prices

The script below uses a read-only archive API (no live Polymarket calls on the read path). Set POLYORDERBOOKS_API_KEY from your dashboard after signup.

Discover a market with GET /v1/markets (search, status, category filters).
Pull GET /v1/markets/{slug}/prices with start_ts, end_ts, and resolution (e.g. 60s on Starter).
Parse data keyed by outcome label; each point has t (timestamp) and p (price). Paginate with metadata.next_cursor for longer windows.
For book depth on the same window, call /v1/markets/{slug}/books instead — same time parameters, ladders in b / a arrays.

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. Pick a market
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 a day of historical prices
end = datetime.now(timezone.utc)
start = end - timedelta(days=1)

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

for outcome, points in payload["data"].items():
    print(outcome, "buckets:", len(points))
    for point in points[:3]:
        print(" ", point["t"], "price", point["p"])

# 3. Need L2 depth? Same window, swap to /books
# books = requests.get(f"{BASE}/v1/markets/{slug}/books", params={...}, headers=HEADERS)

Export to CSV by writing points rows in your loop, or use the official Python SDK on PyPI if you prefer a typed client. Parameter details and response shapes are in the quickstart and historical overview.

Choosing your path

Polymarket historical data spans more than one source. Use Polymarket's own APIs — including documented historical price endpoints — for discovery, trading, and probability time series; use an archive when you need stored order book snapshots, unified exports, or full L2 replay at scale.

A practical workflow: pull prices for the question you have today, validate the signal, then upgrade to /books only if execution realism matters. A free Starter tier is enough to prototype on recent crypto markets — expand resolution or lookback when the research justifies it.

Disclosure: I work on PolyOrderbooks, a hosted historical Polymarket data API. This post reflects how we think about the problem space — not affiliated with Polymarket.

How to Get Historical Polymarket Order Book Data for Backtesting

PolyOrderbooks — Tue, 04 Aug 2026 16:27:23 +0000

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.

Discover a market slug with GET /v1/markets.
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).
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.