Polymarket API guide: market data, order books, historical data, and Python

Polymarket exposes four public APIs and none of them is called "the Polymarket API". This guide says which one does what, what needs a key, how to read markets and books from Python, and where the history comes from once you need more than the current state.

Which Polymarket API does what

Gamma APIhttps://gamma-api.polymarket.com

Markets, events, series, tags, and search. Metadata, outcomes, token ids, volume, liquidity. Key: none.

CLOB APIhttps://clob.polymarket.com

The current order book per token, midpoints and spreads, one price series per token, and order placement. Key: none to read, wallet keys to trade.

Data APIhttps://data-api.polymarket.com

Positions, activity, and holder data by wallet. Key: none.

WebSocketwss://ws-subscriptions-clob.polymarket.com/ws/market

Live book snapshots and price changes for subscribed tokens. Key: none.

Reading is open: no account, no key. Placing orders goes through the CLOB API with requests signed by your wallet. Per endpoint rate limits are documented at docs.polymarket.com and enforced per IP for unauthenticated reads.

Market data: list markets with the Gamma API

Gamma is the catalog. Filter by activity, closed state, tag or slug, sort by 24 hour volume, and read clobTokenIds, a JSON encoded list with the YES token first, to get the outcome tokens every other endpoint is keyed by.

python

import json, requests

markets = requests.get(
    "https://gamma-api.polymarket.com/markets",
    params={"active": "true", "closed": "false", "limit": 5,
            "order": "volume24hr", "ascending": "false"},
).json()
for m in markets:
    yes_id, no_id = json.loads(m["clobTokenIds"])
    print(m["question"], round(m["volume24hr"]), yes_id[:12])

Order book: the current state only

GET /book?token_id= on the CLOB API returns the bids and asks for one token as they stand now, listed from the worst level to the best, plus the tick size and minimum order. The WebSocket market channel streams the same book and every price change from the moment you subscribe. Neither returns anything from before that moment: a request at 12:00 cannot see the book from 11:59.

python

book = requests.get(
    "https://clob.polymarket.com/book", params={"token_id": yes_id}
).json()
# levels are listed worst to best, so the best quotes are the last entries
print("best bid", book["bids"][-1], "best ask", book["asks"][-1])
print(book["tick_size"], book["min_order_size"])   # the book right now, nothing earlier

Historical data: what the official APIs keep, and what they do not

Kept: one price series per outcome token through GET /prices-history on the CLOB API, at minute fidelity, covered step by step on price history. Not kept: past order books at any depth, executed trades as a history, candles, and bulk downloads. Anyone who wants those has to have been recording when they happened.

Marketlens has recorded every recurring Polymarket market type since March 1, 2026: 903,238 markets, 37.2B order book price changes, 660M full snapshots, 280M trades, indexed by the same series slugs and condition ids Polymarket uses, so a market found on either side is the same market on the other.

python

from marketlens import MarketLens

client = MarketLens()

# the archive uses the same series slugs and condition ids as Polymarket
market = next(client.series.walk(
    "btc-up-or-down-5m", status="resolved",
    after="2026-09-10T12:00:00Z", before="2026-09-10T12:30:00Z",
))
book = client.orderbook.get(market.id, at=market.close_time - 120_000)   # as it was then
trades = client.markets.trades(market.id, after=market.data_start,
                               before=market.data_end).to_dataframe()
print(book.best_bid, book.best_ask, len(trades), market.winning_outcome)

The endpoint list, limits, and tiers are on the historical data API page.

Python: which library for which job

py-clob-client is Polymarket's own package for trading and the live book, and it is the right tool for both. The marketlens package reads history: series, markets, books at any instant, trades, candles, outcomes, exports, and a backtest engine that replays the books. A typical bot uses the first to trade and the second to research and test.

bash

$ pip install py-clob-client marketlens

FAQ

Common questions

Does Polymarket have an API?

Yes, four public surfaces: the Gamma API (gamma-api.polymarket.com) for markets, events, and metadata; the CLOB API (clob.polymarket.com) for order books, prices, and trading; the Data API (data-api.polymarket.com) for positions and activity; and a WebSocket (ws-subscriptions-clob.polymarket.com) that streams order book updates. Read endpoints need no key.

Is the Polymarket API free?

Reading market data from the official APIs is free and needs no account; trading endpoints sign requests with your wallet keys. Rate limits apply per endpoint and are documented at docs.polymarket.com. Historical order books and trades are not served by the official APIs at all; the Marketlens archive serves them with a free tier of 25 million rows per day.

How do I get Polymarket historical data through the API?

The official CLOB API keeps one price series per outcome token (prices-history). Past order books, trades, and candles come from Marketlens, which has recorded every market since March 1, 2026: 903,238 markets, 37.9B order book rows, indexed by the same series slugs and condition ids, through REST and the Python SDK.

Which Python library should I use for the Polymarket API?

For trading and the live book, Polymarket's own py-clob-client. For anything historical (books, trades, candles, outcomes, backtests) the marketlens package. They cover different jobs and are used together.

Try it

The history the official API does not keep

Every book, trade, and candle since March 2026, through REST and Python. The free tier includes 25M rows per day, no card required.

bash

$ pip install marketlens

Get a free API key Read the docs