I went looking for "the Polymarket API" and spent an hour confused before realizing that's the wrong mental model entirely. There isn't one API — there are three separate services with different base URLs, different auth, and different jobs. Here's the map I wish I'd had on day one.
One number that mattered more than I expected: CLOB rate limits sit around 9,000 requests per 10-second window, versus roughly 4,000 on Gamma and 1,000 on Data. Hit those with naive polling and you'll get throttled before you notice — the fix is WebSocket feeds for anything live, not more REST calls.
Polymarket Gamma API: the metadata layer
Gamma answers "what markets exist and what do they look like" — titles, descriptions, end dates, volume, and the token IDs you'll need for pricing elsewhere. Base URL is gamma-api.polymarket.com, fully public, no key, no wallet required. The two endpoints you'll hit constantly are /markets and /events.
One gotcha that costs people an hour: outcome prices come back as a JSON-encoded string, not a real array. market.outcomePrices[0] gives you the character [, not a price — you have to parse it first. Same pattern applies to outcomes and clobTokenIds.
Polymarket CLOB API: where the actual trading happens
CLOB is the live order book and the surface where trading actually happens. Authentication is where it gets confusing: there's no traditional API key to request anywhere on Polymarket. Placing an order always requires signing the request with your Polygon wallet, using EIP-712 plus HMAC. For reading the order book itself, guides don't fully agree — some describe it as public, others show it behind the same HMAC signing used for orders. I'd check the current official docs before assuming either way rather than trust a guide (mine included) on this specific point.
CLOB moved to a V2 contract in April 2026 — worth knowing if you're following an older tutorial, since roughly half the order-struct fields changed and the collateral token switched from USDC.e to pUSD. The official SDK is py-clob-client (Python) — it's the one library that handles CTF contract approval for you, though funding the wallet itself is still on you.
The order-type gotcha nobody mentions upfront
Every order on Polymarket is ultimately an EIP-712 signed limit order under the hood — even the ones the SDK calls "market orders." py-clob-client exposes two paths: OrderArgs for limit orders (GTC, GTD) and MarketOrderArgs for immediate-fill orders (FOK, FAK), but both get signed the same underlying way before submission.
The gotcha that actually costs people failed orders: FOK and FAK market orders enforce stricter decimal precision than GTC limit orders, and the client-side rounding in the SDK has known bugs that produce amounts the server then rejects — maker amount supports at most 2 decimals, taker amount at most 4, and it's easy to end up with a value outside that from a naive size calculation. If your market-style order keeps getting rejected for no obvious reason, check your precision before assuming the API itself is broken.
Polymarket API documentation official
The official docs are the source of truth for exact rate-limit numbers and endpoint schemas — third-party guides (this one included) are useful for orientation, but limits get adjusted and guides go stale faster than the docs themselves. When something in the docs is ambiguous, the Polymarket Discord is where most builders end up — it's faster than filing a support ticket for anything API-specific, and you'll usually find someone who already hit the same edge case.
Polymarket Data API: the one people forget
The third surface, easy to miss if you only read about Gamma and CLOB: the Data API covers historical activity — trade history, and trader leaderboard rankings (older integrations pointed at a separate leaderboard host; as of 2026 that's folded into the Data API, so don't hardcode the old one). It's public, same as Gamma, no wallet needed for reads.
Polymarket API documentation 2026: what changed this year
Beyond the V2 migration, the geo-restrictions at order-placement level haven't shifted — the US, UK, and several EU countries remain blocked from placing orders directly through the CLOB, regardless of whether the site itself loads for someone in that country. That's a detail that trips up a lot of otherwise-working integrations: your reads succeed, your order placement silently fails or gets rejected, and the API error doesn't always make the cause obvious.
Polymarket API docs: where things actually live
The docs themselves are split the same way the API is — no single page covers all three services end to end. If you're bookmarking one thing, bookmark the CLOB section specifically; that's where the order-precision rules, auth flow, and V2 migration notes live, and it's the part that changes most often.
Kalshi API: the comparison everyone asks about
If you're building anything that touches prediction markets, Kalshi comes up immediately as the other major player, and its API looks structurally similar on the surface — public market data, authenticated trading. The practical difference for a builder is less about the API shape and more about market overlap and liquidity depth per contract, which varies by category and isn't something either API tells you directly — you have to compare order books yourself.
What I actually needed for one trade
Gamma /markets?slug=... to find the market and grab the token ID.
CLOB /book?token_id=... to see the live order book — check current docs on whether this needs signing.
Sign an order with the wallet via py-clob-client.
Submit through CLOB, confirm the fill.
No sandbox environment exists — Polymarket doesn't offer a testnet, so the first real test is a real trade with real funds. That's worth planning around before you start.
Where I actually trade
For placing bets on sports and esports markets without touching the raw API myself, I use overdog.bet — a terminal built on Polymarket's liquidity. I follow the live markets and check my own numbers on the proof page, public, no support ticket needed.
Responsible gambling isn't a line to skip. If trading stops being a deliberate decision and starts being a way to cover a budget gap, that's a reason to pause, not size up.
