Polymarket API Guide: CLOB, Gamma, and Data API (2026)

Polymarket’s API surface splits into three public services — Gamma (market discovery), the CLOB (trading and prices), and the Data API (accounts and history) — plus WebSocket streams for live updates. Authentication is two-layer: your wallet signs once to derive API credentials (L2), and those credentials sign every subsequent request.

What does each API do?

Gamma answers “what exists” — events, their markets, resolution rules, tags. The CLOB answers “what’s the price and how do I trade it.” The Data API answers “what happened” — trade history, positions, user activity. Most integrations touch all three in one loop.

How does authentication work?

The flow: sign a one-time request with your wallet → receive apiKey, secret, passphrase → attach them as headers on subsequent calls. Public market data (books, prices, Gamma) needs no auth at all.

What are the key endpoints?

Gamma (discovery):

• GET /events and /markets — paginated listings with filters
• GET /public-search — keyword search across markets

CLOB (trading):

• GET /book?token_id= — full order book for one outcome
• GET /midpoint, GET /price — single price points
• GET /prices-history — historical series
• POST /order, POST /orders — place one or a batch
• DELETE /cancel-all — flatten everything

Data API (accounts):

• GET /v2/positions — open positions
• GET /v2/trades — trade history
• GET /v2/activity — user activity feed
• Leaderboard endpoints (folded into Data API as of 2026)

What changed in the 2026 V2 migration?

• Data API v2 endpoints are the primary surface (/v2/...); v1 paths remain for legacy calls but new features land in v2
• The old leaderboard host is deprecated — use the Data API
• py-clob-client → py-clob-client-v2 for Python (April 28, 2026 cutover)
• Per-signer token-bucket rate limits added on CLOB order/cancel endpoints

Which mistakes break integrations?

1. Polling instead of streaming — WebSocket channels exist for books and fills; REST polling wastes your rate-limit budget and lags
2. Ignoring geoblocking — Polymarket US and perps have separate APIs; hitting the wrong surface from a restricted IP fails confusingly
3. Hardcoding py-clob-client v1 imports — the most common 2026 breakage
4. Missing clock sync — signed requests with stale timestamps are rejected; sync against the time endpoint
5. Treating v1 rate limits as current — per-signer buckets changed the math for active bots

FAQ

Q: Is the Polymarket API free? A: Yes — all three public APIs are free within rate limits. Only trading requires auth and collateral.

Q: What’s the difference between Gamma and the CLOB? A: Gamma is the catalog (what markets exist, their rules); the CLOB is the exchange (live prices, books, order placement). Discovery flows Gamma → CLOB.

Q: Do I need API keys to read prices? A: No — public market data (books, prices, Gamma listings) is unauthenticated. Keys are required for order placement and private account data.

Q: Which SDK should I use in 2026? A: py-clob-client-v2 for Python (the official package since the April 2026 migration); TypeScript clients exist in the official ecosystem for JS stacks.

Q: Where did the leaderboard API go? A: Into the Data API — older integrations pointed at a separate host; that’s deprecated. Update your base URLs.

Sources

• docs.polymarket.com — API Reference
• Polbots — Polymarket API explained

Disclaimer

Not financial advice. Educational purposes only. Updated October 2026.