Polymarket API: Gamma, CLOB, the Data API and the websockets, explained

Ask Gamma for one NFL game and you get 957,967 bytes back. Ask the CLOB for the same game's midpoint and you get 16. Polymarket does not have one API: its getting-started page lists 4 REST services and 4 websocket streams, each owning a different question, and the wrong host either lacks your endpoint or sends you a megabyte you did not need.

Gamma, at https://gamma-api.polymarket.com, is the catalog: events, markets, tags, sports, teams, and the metadata you need before you can read a price. It is where you find a market's slug, its condition id, and the token ids of its outcomes.

The CLOB API, at https://clob.polymarket.com, is the order book. It serves books, prices, midpoints and spreads to anyone, and it takes orders, cancels and heartbeats from authenticated accounts. CLOB stands for central limit order book, the matching system Polymarket runs.

The Data API, at https://data-api.polymarket.com, is the account and activity layer: positions, trades, activity, holders, leaderboards and P&L for any wallet. Version 2, under /v2 since September 4, 2026, wraps every response in a data envelope, pages with cursors and needs no key. /v1 still answers but is frozen.

The Relayer API, at https://relayer-v2.polymarket.com, submits wallet transactions so an account does not need to hold POL for gas. A separate Bridge API at https://bridge.polymarket.com handles deposits and withdrawals.

The websockets split the same way. wss://ws-subscriptions-clob.polymarket.com/ws/market streams public book, price and market lifecycle updates. The /ws/user channel on the same host streams your own orders and trades, and needs credentials. wss://sports-api.polymarket.com/ws streams live game status and scores. The older real-time service at wss://ws-live-data.polymarket.com still carries the public trade activity topic. Reference prices moved on September 15 to their own socket, PolyBolt, at wss://ws-live-v2.polymarket.com/ws, which needs CLOB credentials.

We sent Polymarket 14 calls with no key and no account. All 10 reads answered, and the 4 refusals were the 4 calls about an account: open orders, your trades, deriving an API key and placing an order. Polymarket's getting-started page says the same: public market data is available without credentials, websockets included.

Trading needs two layers. L1 is your wallet signing an EIP-712 message, which proves you control the address and lets you create or derive API credentials: POST /auth/api-key creates a set, GET /auth/derive-api-key returns the one you already have. The response is an apiKey, a secret and a passphrase.

L2 signs each private CLOB request with those credentials using HMAC-SHA256. Every L2 request carries 5 headers: POLY_ADDRESS, POLY_SIGNATURE, POLY_TIMESTAMP, POLY_API_KEY and POLY_PASSPHRASE. An order needs both: L2 authenticates the request, and a wallet signature authorizes the order itself.

The signature type tells the CLOB whose funds an order spends. 0 is a plain wallet (EOA), 1 a legacy Proxy wallet from a Magic Link or Google sign-up, 2 a legacy Safe wallet, and 3 a Deposit Wallet, which Polymarket says every account deployed on or after May 4, 2026 uses. Set it to match how the account was created, or a correctly signed order spends from the wrong address.

A real book is deeper than most people expect. 155 minutes before the Bears played the Packers on October 11, 2026, the Bears' moneyline token had $1.07 million resting at its three best prices on each side, bids at 50¢ to 52¢ and asks at 53¢ to 55¢. A $10,000 buy would have filled entirely at the best ask.

Start with Gamma. curl -G "https://gamma-api.polymarket.com/markets" --data-urlencode "closed=false" --data-urlencode "limit=5" returns 5 open markets. That is the exact example on Polymarket's getting-started page, and it needs no key.

Each market carries clobTokenIds, one token id per outcome. A Yes/No market has 2. Keep the id of the outcome you care about, because every CLOB price call takes a token id, not a market id or a slug.

Then read the book: GET https://clob.polymarket.com/book?token_id=<id> returns the bids, the asks, the tick size, the minimum order size, and whether the market is negative risk. GET /midpoint?token_id=<id> returns one number, the midpoint. POST /books takes up to 500 token ids in one call. The order book guide explains what the bids, asks and spread mean for your fill.

For a wallet, call the Data API: GET https://data-api.polymarket.com/v2/positions?user=<address> lists what that address holds. For price history, GET https://data-api.polymarket.com/v2/prices-history takes a token_id and exactly one of interval, a start and end window of at most 15 days, or as_of. Polymarket moved price history here on September 4, 2026; the older CLOB /prices-history route is still documented.

Polymarket's limits are per IP address and differ 180 times over between services: the CLOB allows 9,000 requests every 10 seconds, the Bridge 50. Cloudflare enforces them over sliding windows and delays and queues what goes over rather than refusing it, so a script that ignores the limit gets slow before it gets errors. The Data API v2 also answers heavy load with 429 and a Retry-After header.

Gamma allows 4,000 requests per 10 seconds in general, 500 per 10 seconds on /events and 300 on /markets. The CLOB allows 9,000 per 10 seconds in general and 1,500 each on /book, /price and /midpoint. The Data API v2 allows 800 in general and 200 on /v2/positions and /v2/prices-history.

Order placement has its own budget: POST /order allows a burst of 5,000 per 10 seconds and 120,000 per 10 minutes sustained. On top of that sits a per-signer budget by 30-day volume tier, from 40 orders a second on Standard to 600 on Elite at $10 million and up, in warning mode since July 24, 2026 with enforcement to be announced. These are the numbers on docs.polymarket.com on October 11, 2026, and they change.

py-clob-client is archived and cannot sign an order CLOB V2 accepts, and it was still downloaded 335,464 times from PyPI in the last month. The unified Python client Polymarket now recommends got 113,609. Downloads count CI runs and mirrors as well as people, but the gap says a lot of code still installs the first-generation package. If yours imports py_clob_client, move it.

Polymarket now ships one client per language across its APIs. For TypeScript, npm install @polymarket/client. For Python, pip install polymarket-client, imported as polymarket. Both handle pagination, errors and wallet setup.

The CLOB-only v2 clients, @polymarket/clob-client-v2 and py-clob-client-v2, are labelled previous in Polymarket's migration guide. The first-generation clob-client and py-clob-client repositories are archived, their last releases from February and March 2026. CLOB V2 went live on April 28, 2026, and Polymarket's changelog says V1 SDKs and V1-signed orders are no longer supported, so a tutorial built on a first-generation package will not place an order today.

For Rust, Polymarket says a unified SDK is in development and points to polymarket_client_sdk_v2 until then. Go straight to the REST APIs when your runtime has no SDK or you need exact control over signing and retries; the getting-started page says the same.

clobTokenIds is a string. In a scan of 3,615 open sports markets on October 11, 2026, every one returned it JSON-encoded, "[\"1075...\",\"7305...\"]", so parse it before you index into it.

A market is not an event. A market is one Yes/No question with its own condition id and 2 token ids. An event groups one or more markets: a game is an event, and its moneyline, spread and totals are separate markets under it. Prices and books are per token id.

Not every market is on the book. Only markets with enableOrderBook set to true trade through the CLOB. All 3,615 sports markets in the scan had it on; filter on it anyway, because a market without it has no book to request.

Prices change type between services. The CLOB returns decimal strings such as "0.085"; the Data API v2 returns money and size as JSON numbers. Prices run from 0 to 1 and read as a probability: 0.62 is 62%.

The tick size moves. Tick sizes run from 0.1 down to 0.0001, 588 of the 3,615 sports markets in the scan ticked at 0.001, and an order off the current tick is rejected. Read tick_size from the book and listen for the tick_size_change event on the market websocket.

Offset pagination is on its way out. Gamma added /markets/keyset and /events/keyset, which page with after_cursor and next_cursor, allow at most 100 rows a page, and reject offset. /markets also defaults to closed=false, so a script looking for settled markets has to ask for them.

Websockets need a heartbeat, and the two hosts differ. On the market channel you send the text frame PING every 10 seconds. On the sports websocket the server sends ping every 5 seconds and you answer pong within 10 seconds.

Location is checked. GET /api/geoblock on the polymarket.com host returns whether your IP is blocked, and orders from a blocked region are rejected. Some countries are blocked outright and some are close-only on the API too; the region guide has the list.

Gamma's sports layer is bigger than any sportsbook menu: GET /sports listed 481 leagues on October 11, 2026, each mapped to its tags, and GET /sports/market-types listed 298 market types. GET /teams?league=nba lists a league's teams, and the events keyset route takes a game_id, so one call returns a game's event.

The sports websocket at wss://sports-api.polymarket.com/ws pushes each game's status, period and score, with no subscription frame needed. In 10 minutes on a Sunday afternoon it sent 483 updates on 43 games, and esports sent 73% of them. Size your handler for the esports slate, not the NFL one.

One rule matters for anyone trading around kickoff: Polymarket cancels outstanding limit orders on a sports market when the game begins. Its docs add that a game starting early can beat the cancellation, so watch your orders near the start.

What Polymarket's API does not return is anything about the people trading. It gives you a wallet's positions and fills. It does not say whether that wallet wins over time, which side of a game the winning wallets are on, or which of today's large trades came from someone with a record.

0xinsider builds Polymarket analytics & infrastructure for sports and esports markets, and its API returns the same data the site runs on. Of its 93 operations, 78 read data and none places an order or touches a wallet; the writes create your own webhooks, export jobs and a sandbox key. You keep trading through Polymarket's CLOB and read the context from 0xinsider.

GET /api/v1/trader/{address} returns a wallet's grade, S to F on settled P&L, with its realized and unrealized P&L, win rate and detected strategy. GET /api/v1/large-trades lists large trades with the wallet and its grade, filterable by size, category and grade. GET /api/v1/market/{condition_id}/flow returns one market's net large-trade flow and its five largest graded positions.

GET /api/v1/games returns one row per game: both sides, the kickoff, live scores, and every linked Polymarket market with its condition id and outcome token ids, so you can go from a game straight to a CLOB book without matching team names. GET /api/v1/leaderboard ranks the S, A and B wallets.

The base URL is https://api.0xinsider.com, with a Bearer token: an API key from the developers page or an OAuth 2.1 access token. Live data needs an active Pro subscription. The OpenAPI 3.1 spec is at https://0xinsider.com/api/v1/openapi.json, and GET /api/v1 lists every route with no key.

You can build before you pay. The sandbox at https://0xinsider.com/sandbox/api/v1 answers every documented operation except the live stream with example data and no credential, and ?sandbox_status=429 returns a rate-limit error to test your retry code. GET https://api.0xinsider.com/api/v1/pick-of-the-day/ledger returns production data with no key: the daily picks, each sealed as a hash before kickoff.

For agents, npx -y @0xinsider/mcp init writes the MCP config for Claude Code, Cursor, Codex or Gemini CLI, and a hosted MCP server runs at https://api.0xinsider.com/api/v1/mcp. The same npm package installs the 0xinsider CLI. pip install 0xinsider gets the Python client. The MCP page covers the setup, and docs.0xinsider.com has the quickstart, the rate limits and every endpoint.