The Polymarket API, explained

The four APIs and what each is for

Gamma API: find markets and events

https://gamma-api.polymarket.com returns events, markets and their metadata: questions, slugs, outcomes, token IDs, end dates and resolution status. Start here to turn a market name or slug into the token IDs every other API needs.

CLOB API: live prices, order books and orders

https://clob.polymarket.com serves the current order book (GET /book?token_id=, or POST /books for up to 500 tokens), midpoints and spreads, and is where orders are placed and cancelled. The book response is a snapshot of now: bids, asks, tick size and last trade price.

Data API: trades, positions and price history

https://data-api.polymarket.com covers trades, positions, activity and price history. Version 2 lives under /v2; Polymarket retires v1 on October 24, 2026, so new code should use v2. /v2/trades is cursor-paginated at up to 1,000 rows per page, and /v2/prices-history returns a price series for one token.

WebSockets: streaming updates

The market channel at wss://ws-subscriptions-clob.polymarket.com/ws/market sends a full book on subscribe, then price_change, last_trade_price and tick_size_change messages. Clients must send PING every 10 seconds. A user channel streams your own orders and fills, and newer sockets carry live reference prices and sports scores.

Quick start: read a live book with no key

# 1. Find a market and its token IDs (Gamma)
curl -s "https://gamma-api.polymarket.com/markets?slug=<market-slug>" | jq '.[0] | {question, tokens: (.clobTokenIds | fromjson)}'

# 2. Read the current order book for one outcome token (CLOB)
curl -s "https://clob.polymarket.com/book?token_id=<token_id>" | jq '{bids: .bids[:5], asks: .asks[:5]}'

# 3. Price history for the same token (Data API v2)
curl -s "https://data-api.polymarket.com/v2/prices-history?token_id=<token_id>&interval=1d"

Parameter names changed between versions: the legacy CLOB /prices-history takes market, startTs, endTs and fidelity, while the v2 Data API route takes token_id with one of interval, start/end or as_of. Check the official docs before relying on either.

Authentication and SDKs

• Public data (Gamma, CLOB reads, Data API) needs no credentials.
• L1 is an EIP-712 wallet signature used to create or derive CLOB API keys.
• L2 is HMAC-SHA256 request signing with POLY_* headers, needed for private CLOB routes and orders.
• SDKs: use py-sdk or ts-sdk. The older py-clob-client and clob-client repos are archived after the CLOB V2 upgrade, so tutorials that use them are out of date.

Rate limits

Limits are per IP, enforced by Cloudflare, and excess requests are throttled rather than rejected. Figures below are per 10 seconds, from Polymarket's rate-limit page as of 2026-09-27:

• CLOB: 9,000 overall; /book 1,500; /books 500; /prices-history 1,000.
• Gamma: 4,000 overall; /markets 300; /events 500.
• Data API v2: 800 overall; /v2/trades 300; /v2/prices-history 200.

Order placement has its own limits per signing wallet, tiered by trading volume.

What the Polymarket API does not give you

• Historical order books. /book is live only. There is no endpoint for the bids and asks at a past moment, so spreads, depth and slippage in the past cannot be reconstructed from the official API.
• Fine-grained history for old markets. 1-minute price buckets are kept for at least 7 days; older data is coarser, down to 12-hour buckets for the full history.
• A defined "price". The docs do not say whether price history is a midpoint or a last trade, which matters when you backtest entries against it.

This is the gap Resolved Markets fills. It has recorded full-depth Polymarket order books since March 2026: 4.2B+ orderbook snapshots, with trades and settlement results, queryable by market and time. See what is covered and how to query it.