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

Polymarket does not have one API. Its getting-started page lists 4 REST services on 4 hosts and 4 websocket streams, and each one owns a different part of an integration. Pick the wrong host and the endpoint you want is not there.

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 lives under /v2 and needs no API key.

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.

Reading needs nothing. Polymarket's getting-started page says it directly: public market data is available without credentials. Gamma, the Data API, the CLOB's books and prices, and the market and sports websockets all answer an anonymous request.

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.

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.

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.

0xinsider.com/learn/how-to-read-polymarket-order-book explains what the bids, asks and spread in that response mean for your fill.

Polymarket's limits are per IP address, enforced by Cloudflare over sliding windows. Go over one and your requests are delayed and queued rather than refused at once, so a script that ignores the limit gets slow before it gets errors.

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. Polymarket also documents a per-signer order budget by volume tier; the docs describe it in warning mode, with enforcement to be announced. These are the numbers on docs.polymarket.com on September 28, 2026. Read the rate limits page before you size a poller, because they change.

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 earlier CLOB-only clients, @polymarket/clob-client-v2 and py-clob-client-v2, are now labelled previous in Polymarket's migration guide, and the first-generation clob-client and py-clob-client repositories are archived. 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. Gamma returns 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. Filter on it before you request a book that does not exist.

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, 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, some are close-only on the API too. 0xinsider.com/learn/polymarket-not-available-in-your-region covers the list.

Gamma has a sports layer. GET /sports maps each sport to its tags, GET /sports/market-types lists market types such as spreads, and GET /teams?league=nba lists a league's teams. 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. Status values are listed per sport, esports included.

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. Every endpoint is read-only, so nothing in it places an order. 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 shows which side the graded wallets' money is on in one market.

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 0xinsider.com/developers or an OAuth 2.1 access token. Live data needs an active Pro subscription (0xinsider.com/pricing). 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 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. 0xinsider.com/mcp covers the MCP setup, and docs.0xinsider.com has the quickstart, the rate limits and every endpoint.