The Polymarket API, Mapped: Gamma vs CLOB vs Data API

The first thing to understand about the Polymarket API is that there is no such thing. There are four REST APIs and four WebSocket streams, each serving a distinct part of an integration, each on its own hostname, with its own rate limits and its own auth requirements.

Almost every "the Polymarket API doesn't have X" question turns out to be "X is on a different host". Here is the whole surface in one place.

The four REST APIs

Gamma API — discovery and metadata

Gamma is where you start. It answers what exists: events, the markets inside them, tags, search, and the metadata you need to work with anything else — critically, the token IDs that every CLOB endpoint requires.

• /events — list events, with keyset pagination available
• /markets — list markets; also by id, by slug, by token
• /public-search — search across events and markets
• /tags, /comments — taxonomy and discussion
• Open interest, live volume, top holders

CLOB API — prices, books and orders

The order book itself, and the only place you can trade. Reading is public; trading needs credentials.

Data API — positions and activity

Portfolio-shaped questions: /positions, /closed-positions, /trades, plus the user PNL API. Note that this is the tightest of the three main APIs — a general limit of 1,000 req / 10s, with /positions and /closed-positions at just 150 req / 10s each. It is designed for dashboards, not for polling loops.

The four WebSocket streams

If you are polling /book on a timer, stop — this is what the streams are for. Polling is the single most common way to burn a rate limit budget for no benefit.

The User channel is the one people miss. If your bot polls /data/orders to find out whether its order filled, you are paying rate limit budget for information the User channel would have pushed to you the moment it happened — and with lower latency.

Authentication: L1 and L2

Public market data needs no credentials at all — you can hit Gamma, the CLOB read endpoints and the Data API with a bare curl. Trading needs two layers, and understanding which is which resolves most auth errors.

Order placement uses both: L2 authenticates the request, and a wallet signature authorises the order. The L1 typed data is a ClobAuth payload on chainId: 137 (Polygon), with your signer address, a Unix timestamp in seconds, a nonce (use 0 unless you are managing multiple credential sets), and the fixed message string.

Getting an API key

1. Sign the ClobAuth EIP-712 payload with your Polygon private key.
2. Call POST /auth/api-key with the L1 headers to create credentials. You get back a key, a secret and a passphrase — all three are required for L2.
3. On subsequent runs, call GET /auth/derive-api-key to retrieve the existing credentials instead of creating new ones.

SDKs

Polymarket maintains unified TypeScript and Python SDKs that wrap all of the above with a typed interface and handle pagination, error shapes and wallet setup. If you are starting fresh in either language, use them — hand-rolling EIP-712 signing and HMAC request signing is a genuinely error-prone way to spend a weekend.

Go direct to REST when your runtime is not covered by an SDK, when you need exact control over signing, headers, retries or transport, or when you need an endpoint the SDK has not exposed yet. Note that these are the unified SDKs — if you are on an older client, there is a documented migration path, and older clients are where a lot of stale-credential bugs come from.

What does the Polymarket API cost?

Nothing. There is no paid tier, no API pricing page and no subscription — Polymarket's APIs are free to use, with access governed by rate limits rather than billing. Public market data does not even require a key.

The only thing that scales with money is the per-signer trading limits, which are tiered by your maker wallet's 30-day volume — from Standard at 40 order tokens/sec up to Elite at 600 — but that is a throughput allocation, not a fee.

The one thing none of these APIs will give you

Having mapped the whole surface, the useful thing to know is what is not on it: historical order book depth.

Every endpoint above serves current state. /book returns the book now. /prices-history gives you a price series, not the depth behind it — so it cannot tell you what your fill would have been. And when a market resolves it disappears from the public feeds, taking its history with it. There is no plan, key or rate limit tier that changes this.

That gap is why backtesting a Polymarket strategy needs a separate data source that recorded the book while markets were running. PolyTest does exactly that for crypto Up/Down markets — 90M+ point-in-time snapshots with 8 levels of depth per side, sub-second timestamps, and resolved markets kept rather than dropped. One header, clean JSON, and a free tier:

curl -H "X-API-Key: $POLYTEST_KEY" \
  "https://api.polytest.io/api/v1/markets?coin=btc&market_type=5m&limit=20"

Full endpoint reference in the PolyTest docs, or start free — no card required.