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 guide maps the published API surfaces and operational checks. Primary contracts and selected public GET response shapes were checked October 8, 2026; the review did not authenticate an account, submit orders or verify every production integration.

If you want a hands-on code walkthrough instead of an orientation, see our Polymarket API Python tutorial — that post scopes token-based examples to a named SDK version; this one is the map.

The Main API Surfaces

Polymarket exposes data and trading through separate services. The four surfaces below serve common workflows, 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 positions, activity, trade history and analytics. Data API v2 introduces a shared response envelope and cursor pagination; legacy v1 and current v2 routes are not interchangeable. Use authenticated CLOB endpoints for 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. REST polling can suit bounded prototypes; update-driven strategies still need a WebSocket freshness and reconnect policy.

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

The official API overview lists these hosts; this table connects them to example tasks.

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.

These contracts are a starting point; version changes and your own account lifecycle still require verification.

Operational Checks Your Application Still Owns

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. This review did not measure a settlement-time distribution. If your bot assumes "match ended → I can redeem immediately" you will get failed redemption calls. Use the resolution state and redeemability required by the selected position system; a final scoreboard is not proof redemption is ready.

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. The retained CLOB-specific examples use py-clob-client-v2 1.2.0. Its README distinguishes token_id from position_id routing; do not mix package APIs, position identifiers or signing versions. New projects should start with the unified SDK recommendation.

Reasons to use raw HTTP: - Custom WebSocket lifecycle and persistence logic. - Endpoints not yet wrapped (Polymarket ships new endpoints faster than the library updates). - A language or runtime not supported by the official SDKs; Node.js has an official TypeScript SDK and does not by itself require custom signing.

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 official error reference documents structured and HTTP error responses. Preserve status/body and classify against the contract for your endpoint and SDK version. 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: Inspect the package, identifier type and server-selected signing route. A legacy V1 payload is one cause, but current token/position version mismatches need the appropriate route. See the focused V2 debugging guide.
• Tick-size rejection: Read the selected market’s tick size and validate the intended price against it. Do not round every market to one cent; changing a limit can also change its execution cost.
• 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: Check acceptance, status, side, limit price, remaining size and changing liquidity. A resting buy below the ask or sell above the bid may be behaving as intended.
• 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.
• Historical depth sources — Inspect the current official prices and order books documentation and any recorded archive for the exact supported query, observed window and sampling. This article’s former /orderbook-history endpoint claim was not confirmed in the checked CLOB reference and is removed; that is not a claim that no other service can supply book history.
• 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. A price-history endpoint is not a depth replay. Validate any recorded source’s clocks, retention, update completeness and granularity. A snapshot archive can miss intervening book changes.
• 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. The endpoints discussed here are paginated/query-filtered resources, not a verified complete-year export. Define the market universe, requested range and observed coverage before claiming a full historical dataset.
• 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 token-based CLOB examples, inspect the py-clob-client-v2 source and the current contracts reference. For new projects begin with the unified SDK, and distinguish CTF token-backed markets from position-backed markets. The signing logic, fee lookup, neg-risk routing, and wallet integration are inspectable there.

Keep the exact package/contract versions with recorded request and execution evidence. Local logs must be reconciled with exchange and wallet state rather than treated as an independent source of 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.