Polymarket API Docs: CLOB, Gamma, Python Gotchas

The official Polymarket API documentation at docs.polymarket.com now describes CLOB V2, deposit wallets, per-market fees, and WebSocket heartbeats in useful detail. The operational challenge is joining those pieces correctly — especially when an older tutorial still shows V1 packages, USDC.e collateral, or a pre-V2 wallet flow.

This is a practical guide to navigating Polymarket's API surface in 2026 based on running bots against it daily. We will cover what is well-documented, what is poorly documented, and what you have to figure out from the source code or from experience.

If you want a hands-on code walkthrough instead of an orientation, see our Polymarket API Python tutorial — that post is copy-paste code; this one is the map.

The Four API Surfaces

Polymarket exposes data and trading through separate services. A production integration normally touches four surfaces, and their identifiers are not interchangeable.

1. CLOB V2 API — https://clob.polymarket.com The Central Limit Order Book. This is where trading happens. Read orderbooks, place orders, cancel orders, check fills, and query market-level tick, order-size, neg-risk, and fee parameters. The endpoint clob.polymarket.com/prices-history?market={token_id} returns historical price series, which is useful for backtesting and CLV (closing line value) measurement.

2. Gamma API — https://gamma-api.polymarket.com Market discovery and metadata. You list available markets, resolve category or league tags to numeric IDs, filter listings with tag_id, and resolve human-readable slugs to token IDs. The Gamma API is what you use to find a market; the CLOB API is what you use to trade it.

3. Data API — https://data-api.polymarket.com Public user positions, activity, trade history, holders, open interest, and analytics. Use this for public portfolio or market analysis; use authenticated CLOB endpoints for your private order-management state.

4. WebSocket streams — wss://ws-subscriptions-clob.polymarket.com Real-time order book updates, market events, and your own fill notifications. For any latency-sensitive use case (in-game sports trading, live market making) you need this. Polling the REST CLOB endpoint every second is both rude and too slow.

CLOB V2 became production on April 28, 2026. The host did not change, but the signed order format, contracts, collateral, and supported client packages did. That unchanged hostname is why V1 code can look current while being production-incompatible.

The official docs document each service, but your application still has to join event IDs, condition IDs, and asset/token IDs correctly across them.

A Quick Map: What You Use Where

Keep this table handy. The official docs will not show it to you in one place.

What the Official Docs Cover Well

In our experience, these areas of the docs are clear and accurate:

• Authentication setup. The L0/L1/L2 credential model (API key + secret + passphrase + wallet private key) is correctly explained, including how to generate the API credentials from your wallet signature.
• Basic order placement. The V2 order schema, GTC/FOK/FAK/GTD behavior, and price/size encoding are documented and the official py-clob-client-v2 library implements them.
• Market data endpoints. The shape of /book responses, the /markets listing format, and the /trades history endpoint are reasonably documented.
• Order book mechanics. The CLOB matching rules, tick size, minimum order size, and decimal price representation (0.50 for 50¢) are documented.

If you stay within these areas, the docs will not steer you wrong.

What the Official Docs Cover Poorly

These are the gaps where you will lose hours if you do not know to look for them:

1. Never hardcode V1 Exchange or neg-risk addresses. CLOB V2 has new verifying contracts for standard and neg-risk markets. Let the V2 SDK resolve market type, or obtain it from current CLOB metadata. An address copied from a pre-April-2026 example signs against the wrong domain.

2. Wallet paths are not interchangeable. CLOB V2 supports EOA (0), existing Polymarket proxy (1), existing Gnosis Safe (2), and the deposit-wallet POLY_1271 flow (3). New API users should use deposit wallets with type 3; existing proxy and Safe accounts can retain their current type. In every case, funder must be the address that holds the collateral for that wallet path.

3. Rate limits are endpoint-specific. The official table has separate limits for books, prices, history, ledger reads, and trading, plus sustained limits on order operations. Code against the relevant endpoint limit and handle throttling instead of copying a single “100 requests/second” number.

4. WebSocket lifecycle is application work. The market and user channels require the client to send PING every 10 seconds. A production client still needs reconnect, backoff, re-subscription, stale-socket rejection, and snapshot reconciliation after reconnecting.

5. Settlement timing. Markets resolve via UMA oracle, and the time between event end and on-chain settlement varies. Most sports markets settle within minutes, but some take longer. If your bot assumes "match ended → I can redeem immediately" you will get failed redemption calls. Wait for the on-chain resolved flag, do not infer settlement from external sources.

6. Fill evidence can arrive in two stages. V2 order responses can include transactionsHashes; when a transaction hash is not available yet, they can return tradeIDs that you follow through trade history. Do not treat the submitted limit as the execution price, and do not assume the hash is present synchronously.

The V2 Python Client vs Raw HTTP

The py-clob-client-v2 Python library handles CLOB V2 authentication, request signing, per-market details, and order operations. The old py-clob-client repository is archived and its V1-signed orders are not accepted by production.

Polymarket also publishes a newer unified Python package, polymarket-client, for workflows spanning more than the CLOB. For a CLOB-specific bot, use a supported V2 client and pin its version; do not mix V1 examples into either SDK.

The 10% case for raw HTTP: - Custom WebSocket lifecycle and persistence logic. - Endpoints not yet wrapped (Polymarket ships new endpoints faster than the library updates). - Cross-language environments (Node.js, Go) where you would need to reimplement signing anyway.

For raw HTTP, signing is the trickiest part. L1 uses an EIP-712 wallet signature; L2 uses HMAC-SHA256 with the API secret and requires all five POLY_* headers. Use the SDK or copy the current official reference implementation exactly rather than reconstructing the canonical message from an old blog post.

Authentication Tiers — When You Need What

Polymarket-style tier terminology in their docs separates read access from authenticated trading from on-chain operations. A practical mapping:

• Public read (no credentials): Market discovery via Gamma, public Data API activity/trades, and CLOB orderbook/price reads.
• Authenticated trading (API key + wallet signer): Place and cancel orders and read account data. Requires API key, secret, passphrase, a signer, the correct signature type, and the funder address.
• Wallet/on-chain operations: Fund, approve, merge, redeem, or move collateral. EOA and deposit-wallet/relayer flows differ; follow the wallet-specific V2 documentation rather than manually copying a Safe transaction pattern.

The CLOB API documentation covers the first two reasonably well. The third — on-chain redemption — is where most production gotchas live, because most users do it through the web UI and never hit the documentation gap.

Rate Limits in Practice

The current rate-limit table is explicit and can change independently by endpoint. At the time of this update it lists, among other values, /book at 1,500 requests per 10 seconds and /prices-history at 1,000 per 10 seconds. Trading endpoints have both burst and 10-minute sustained limits.

Those are ceilings, not polling targets. Use batch endpoints, cache immutable metadata, prefer WebSocket market data, and apply exponential backoff when throttled. Centralize your rate limiter across processes that share credentials so several bots cannot collectively exceed a limit.

Common Error Modes and What They Mean

The CLOB API returns error messages as plain strings rather than typed error codes, which makes pattern-matching them in code slightly annoying. The categories you will hit most:

• "Insufficient balance" / "not enough allowance": Check pUSD and allowances on the configured funder. Collateral on a different EOA, proxy, Safe, or deposit wallet does not fund this order.
• order_version_mismatch: The process is usually signing a V1 order, using the archived package, or constructing a raw order against the wrong V2 domain. See the focused V2 debugging guide.
• Tick-size rejection: Polymarket markets have a minimum tick size (typically 1 cent on standard sports markets). Orders priced between tick increments are rejected. Round prices to the nearest cent before submitting.
• Min-order-size rejection: Each market publishes its current minimum order size. Read min_order_size from the book or mos from CLOB market info instead of assuming one global dollar or share minimum.
• Order placed but never fills: Usually means you priced below the bid or above the ask without intending to. Re-read the orderbook before assuming the API misbehaved.
• Maker or signer rejected: The wallet signature type, API-key identity, and funder do not describe the same wallet path.

Data Endpoints for Backtesting

If you are building backtests rather than live trading, the endpoints you care about most:

• /prices-history?market={token_id}&interval=max&fidelity={N} — Historical price series for a token. fidelity is expressed in minutes: 5 means five-minute points and 60 means hourly points. Use startTs/endTs for explicit ranges instead of combining them with a relative interval.
• Trade history — Use the public Data API for public trade analysis or authenticated CLOB trade methods for your own account. Useful for comparing actual execution prices with contemporaneous quotes.
• /orderbook-history — The current API documents historical book queries by condition or asset ID. Check its available retention and sampling before treating it as a complete depth archive.
• Market resolution endpoint — Once a market resolves, the metadata includes the winning outcome and the resolution timestamp.

An important correction: fidelity=5 is five minutes, not five seconds. It is too coarse to reconstruct a five-second in-game decision path. Sub-minute execution research needs event-time trades plus WebSocket book capture or another suitably timestamped depth source.

What the API Still Does Not Give You Automatically

A few things still require your own data engineering:

• A guaranteed exhaustive depth tape. The documented orderbook-history endpoint is useful, but you still need to validate retention and granularity. Capture the market WebSocket if every sequence of book changes matters.
• Implied volatility or theoretical pricing. Polymarket gives you market prices, not derived metrics. You compute your own fair-value estimates externally.
• Bulk historical data export. No "give me all 2024 sports trades" endpoint. You have to crawl per-market.
• Your own historical execution-quality model. The API can expose the market fee and your fills, but it cannot tell you how much adverse selection your strategy will suffer. You must measure fill-to-mark and fill-to-close outcomes yourself.

For a more thorough discussion of Polymarket's fee structure, see our Polymarket fees explained post.

A Realistic First Integration

If you are starting an integration today, the order we recommend:

1. Hit the Gamma API anonymously and pull the list of active sports markets. Confirm you can resolve a slug to a condition_id and token_id.
2. Hit the CLOB /book endpoint for one of those tokens. Confirm you can read the bid/ask.
3. Set up the WebSocket subscription for that same token. Confirm you receive updates when the book moves.
4. Generate L1/L2 credentials, configure the correct wallet type, fund that address with pUSD, and read its current balance and allowance.
5. Read the selected market's minimum order size, tick size, neg-risk flag, and fee details. Place a valid small resting order and cancel it.
6. Place a real order and let it fill. Confirm the user-channel update, trade ID, actual execution price, and eventual transaction hash.
7. Wait for the market to resolve. Redeem your winnings (or accept your loss). Confirm the wallet-specific redemption flow worked.

Each step exercises a different API surface and authentication tier. Doing them in this order means you fail in isolated chunks rather than discovering several issues simultaneously when you try to ship.

When to Stop Reading the Docs and Start Reading the Source

For everything described here as an operational edge case, the next move is reading the py-clob-client-v2 source and the Polymarket contracts on GitHub. The signing logic, fee lookup, neg-risk routing, and wallet integration are inspectable there.

Treat the official docs as the orientation, the library source as the reference, and your own production logs as the ground truth.

Related deeper reads: - Polymarket API Python Tutorial — the hands-on companion to this orientation. - Polymarket Fees Explained — the cost side that affects every trade. - The Complete Guide to Prediction Market APIs — Polymarket in the context of Kalshi and sportsbook APIs. - Hold to Settlement, Never Sell — strategy implications of the fee and API mechanics.