What each of Polymarket's APIs holds, and which one you need

How it works

Polymarket's international platform is not one API. Its own developer page lists four REST hosts and four WebSocket endpoints, and the API reference adds a bridge host and a combos host beside them. Each answers one kind of question, and each is keyed by a different identifier, which is where most integrations first go wrong: a value that works as a key on one host is rejected or silently ignored on the next.

So start with the identifiers, because every surface below is described by which one it takes.

Four identifiers, and where each comes from

• Slug and Gamma ID. An event groups one or more markets; each market is one yes-or-no question. Both carry a human-readable slug — the one in the website URL — and a numeric ID that Gamma assigns. Polymarket's market-details page gives these one use only: fetching a known market from Gamma, or linking to its page.
• Condition ID. The market's on-chain identifier, 0x and 64 hex characters. It is what the Data API filters on, and it is what positions, resolutions and holders are recorded against.
• Token ID. Each outcome — YES and NO — is a separate conditional token with its own ID. Books, prices, price history, the market stream and orders are all keyed by this, not by the market. Gamma returns a market's outcome labels, prices and token IDs as JSON-encoded arrays inside strings, correlated by position: index 0 is YES, index 1 is NO.
• Wallet address. Two of them, and they are not the same. The key that signs is one address; the account wallet that holds the money and the positions is another. Since 4 May 2026 every new account wallet is a deposit wallet; older accounts hold a proxy wallet (Magic Link or Google sign-in) or a Safe (MetaMask and similar), per Polymarket's wallet-types table. Wallet rows on the Data API are keyed by the account wallet. Query by the signer and you get nothing back, without an error.

Gamma: what is listed

gamma-api.polymarket.com. Events, markets, series, tags, sports teams, comments and a search endpoint, plus the per-market state a catalogue needs: active, closed, acceptingOrders, archived, restricted (geo-restricted for some jurisdictions), the tick size, the minimum order size, and negRisk, which says the market belongs to a neg-risk group whose outcomes are linked by conversion. The rules text — which source settles the market — lives here too, which is why reading a market's rules is a Gamma job.

No key. History is a catalogue's history: closed markets stay discoverable, and archived ones are read-only with no further resolution updates. It holds no order book and no price series — only the current outcome prices on the market record.

The CLOB: what it costs now, and where orders go

clob.polymarket.com. Read side: the book, best price, midpoint, spread and last trade price for a token, each in single and batch form, plus tick size, fee rate and whether a token is neg-risk. All keyless. Write side: placing and cancelling orders, open orders, your own trades, balances and allowances, notifications, and the liquidity-rewards and rebate reads for your account.

Authentication is two layers, per Polymarket's API page. L1 is an EIP-712 ClobAuth message signed by the wallet, which creates or derives an API key, secret and passphrase. L2 is an HMAC-SHA256 signature over every private request made with those credentials. An order then needs both: L2 to authenticate the request and a wallet signature to authorise the order itself. Session keys, in beta, let a deposit wallet's owner authorise a separate signer for up to 180 days that can trade but cannot withdraw; authorising one requires a builder API key, and during the rollout Polymarket enables that by email. The place an order from code walkthrough has the sequence.

Being able to read the book proves nothing about being allowed to trade it. Polymarket's geographic restrictions page says orders submitted from blocked regions are rejected, and documents a check — GET /api/geoblock on the main polymarket.com host, not on any API host — that returns blocked with the country and region for the requesting IP.

History: none worth the name. The CLOB is the present tense. It still documents GET /prices-history in its OpenAPI description, but the 4 September 2026 changelog entry names the Data API route as the replacement, and no part of Polymarket serves a past order book.

The Data API: who holds what, and the past

data-api.polymarket.com. Every wallet's positions across their whole lifecycle (open, redeemable, redeemable-lost, mergeable, closed), activity, trades, portfolio value, PnL series and profile stats; per market, the top holders, open interest, live event volume and resolution state; the trader and builder leaderboards and a biggest-winners board; and the price series for an outcome token. No key. The Data API card has the endpoint list.

Two versions answer on the same host. v2 sits under /v2, wraps every response in data, pages by opaque cursor, and names markets with condition, up to 20 condition IDs per request. v1 pages by offset, stops at 10,000 rows, and is retired on 24 October 2026 according to the migration guide — one route, /v1/accounting/snapshot, excepted.

History is the deepest of any Polymarket surface, with two caveats from the v2 overview. /v2/activity floors an omitted start to three years back, so a full export sets start explicitly. And price history is graded: twelve-hour points are kept for every token's whole life, three-hour points from July 2026 onward, and finer grains only for a rolling window. Where a dashboard gets its data has the windows and what they cost a chart.

It is built from Polygon events, so it trails the chain. GET /v2/status reports the lag per source; read on 4 October 2026, the most-lagged source was two blocks behind.

The sockets: four of them, and one is being replaced

• CLOB market channel, wss://ws-subscriptions-clob.polymarket.com/ws/market. Keyless, by token ID: book snapshots, price changes, last trade prices and tick-size changes, plus best bid and ask and new-market and market-resolved events once the subscription sets custom_feature_enabled. The client sends PING every 10 seconds. Stream an order book covers keeping a local copy in step.
• CLOB user channel, /ws/user on the same host. L2 credentials; your own orders and trades.
• Sports, wss://sports-api.polymarket.com/ws. Keyless game status and scores. Here the server sends ping every 5 seconds and closes the connection if pong does not come back within 10.
• RTDS, wss://ws-live-data.polymarket.com. Public trade activity, and the crypto and equity reference prices as legacy topics, which the migration guide says are planned for removal one month after the TypeScript SDK's 0.11.0 release. Their successor since 15 September 2026 is PolyBolt at wss://ws-live-v2.polymarket.com/ws, which requires CLOB API credentials, caps a connection at 64 subscriptions and 20 subscribe frames a second, and opens every subscription with a snapshot of the preceding two minutes. The migration guide keeps the activity topic on RTDS, retires the live comments stream with no streaming replacement, and drops the 30-second TWAP topic outright. Since 2 October 2026 the crypto channel defaults to Chainlink, with a provider filter to pin Pyth on six symbols.

None of these is on the Data API, which has no stream: following a wallet live means polling it or reading RTDS activity.

Three hosts that move money, not data

• Relayer, relayer-v2.polymarket.com: submits the account wallet's on-chain transactions, such as approvals and redemptions, so the account needs no POL for gas.
• Bridge, bridge.polymarket.com: deposit addresses on other chains, quotes, withdrawals and status, converting to pUSD on Polygon.
• Combos RFQ, combos-rfq-api.polymarket.com: quote requests for multi-leg combo positions. Market makers have a 400-millisecond window to quote and the requester 10 seconds to accept, per How Combos Work. Combo positions and activity read back through the Data API's /combos routes.

The chain, and the subgraphs that stopped

Everything that settles lands on Polygon — fills, balances, splits, merges, redemptions — and Polymarket's data resources page points at Goldsky, Dune and Allium for it rather than at any service of its own. What it no longer points at is a subgraph. Goldsky's Polymarket page says that on 28 April 2026 Polymarket moved to v2 contracts "and is no longer using subgraphs going forward", and that existing public subgraph endpoints "will return incomplete or incorrect data". A tutorial that opens with a GraphQL query against a Polymarket subgraph describes the world before that date. The replacements are the Goldsky datasets as a pipeline into your own database, or Dune in SQL.

The chain carries no rules text, no slug and no order that never filled. That half is Gamma's and the CLOB's, and it exists nowhere else.

Polymarket US: nothing ports

Polymarket US is a separate exchange — a CFTC-designated contract market trading in dollars — and a separate stack. Its introduction splits it in two: gateway.polymarket.us, keyless, for markets, events, series, sports, search, books, best bid and offer, settlement prices and price history; and api.polymarket.us, keyed, for orders, portfolio, balances, and both WebSockets — the markets stream as well as the private one.

Everything that matters is different. Markets are addressed by slug, not by token or condition ID. A key comes from the developer portal only after the iOS app's identity check, and requests carry three headers signed with an Ed25519 key, with a timestamp in milliseconds that must be within 30 seconds of server time, per the authentication page. There is no wallet, no pUSD and no on-chain record, so nothing in the international Data API, Dune or Goldsky covers it.

Where the same word means two things

Price. The CLOB serves four prices for one token — best bid, best ask, midpoint, last trade. The number on the website is a fifth rule: per Polymarket's help article, the midpoint, unless the spread is wider than 10 cents, when it is the last traded price. On Polymarket US, price history is neither: longPrice is the YES display price derived from the best ask, shortPrice is one minus the best bid, and the two can sum to more than 1 because they keep the spread. A chart that mixes venues is plotting different quantities.

Trades. GET /data/trades on the CLOB returns the authenticated account's own trades and needs a key. GET /v2/trades on the Data API returns anybody's, keyless. They are not two views of one table, and a script that swaps one for the other is reading a different population.

Market. CLOB GET /prices-history takes a parameter called market that its OpenAPI description defines as the asset ID — a token, not a market. The Data API's replacement calls the same value token_id. Pass a condition ID to either and you get no series.

Volume. The Data API's own conventions say bare volume and size are shares, _usdc fields are dollars, and fields prefixed taker_ count one side of each trade. A figure without its prefix is not comparable with a dashboard's, which is the subject of why two dashboards disagree on volume.

Over the limit. The rate-limit page says Polymarket's Cloudflare limits delay or queue excess requests rather than reject them. The Data API v2 overview says heavy load answers 429 with Retry-After. Polymarket US always answers 429 — and also sends Global Rate Limit Exceeded on orders it rejects under a five-second latency stopgap, which its rate-limit page says is not a rate limit and should not be backed off from. Code that treats every slow or refused request the same way is wrong on at least one of the three.

What it costs

Nothing, for any of it. No Polymarket host sells a data plan or a key tier. The budget is the request rate, all per IP address. From the international table, read on 4 October 2026, per 10 seconds unless stated:

Order placement is metered twice: POST /order allows a burst of 5,000 per 10 seconds and 120,000 per 10 minutes sustained. Polymarket US allows 25 requests a second across its retail API, counted per source IP and Cloudflare location — so several keys on one machine share one counter — with the combo and RFQ creation and listing routes at 1 a second. Why your bot gets throttled covers what those numbers do to a polling loop.

What you can do about it

Decide the question before the host, then follow the identifier.

Four habits save most of the debugging:

1. Store all three market keys at discovery. When Gamma hands you a market, keep its slug, its condition ID and both token IDs, with the index-0-is-YES mapping, in one row. Every later call needs one of them and none of the hosts converts between them for you.
2. Write against v2 now. Anything still calling Data API v1 has until 24 October 2026, and the envelope, pagination, field casing and market parameter all change. Anything still subscribed to RTDS reference prices needs CLOB credentials to move to PolyBolt before those topics are removed.
3. Check the date on any example that uses a subgraph. If it predates 28 April 2026, it is reading contracts the platform has left.
4. Use an SDK if your runtime has one. Polymarket's unified polymarket-client for Python and @polymarket/client for TypeScript put Gamma, the CLOB, the Data API and the sockets behind one client and handle the L1 and L2 signing. PolyBolt support in the TypeScript package starts at version 0.11.0. For Polymarket US the equivalent is its own pair of SDKs, which share nothing with these.

Then re-read the changelog before trusting any of this page's numbers. Between 4 September and 2 October 2026 Polymarket shipped a new Data API, a new price socket and two changes to that socket's defaults.