Polymarket API Documentation: A Practical Guide to What the Docs Don't Tell You

The official Polymarket API documentation at docs.polymarket.com is reasonably complete for the happy path. It is less complete for the operational realities — how to handle neg-risk markets, when to use proxy wallet signing, what fails silently in production, and how the three different API surfaces actually fit together.

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 Three API Surfaces

Polymarket exposes its functionality through three different APIs, each with a different purpose. The official docs treat them as separate sections, but you need all three to build anything real.

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

2. Gamma API — https://gamma-api.polymarket.com Market discovery and metadata. You list available markets, filter by tag (sports, politics, etc.), 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. 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.

The official docs document each of these in isolation. The thing they do not explain well is which one you need for which task and how to chain them — that you have to learn by building.

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 order schema, the order_type enum (GTC, FOK, GTD), and the price/size encoding are documented and the official py-clob-client library implements them correctly.
• 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, the tick size, and the integer-cent price representation (you express prices as 0-100 cents, not 0-1 probabilities) are well-explained.

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. Neg-risk markets have different token IDs. Multi-outcome markets (championship winners, "which candidate wins") use the neg-risk adapter contract (0xd91E80cF2E7be2e162c6513ceD06f1dD0dA35296). Crucially, the neg-risk wrapped token IDs that you receive when you buy are different from the CLOB token IDs you traded against. If you try to redeem winnings using a CLOB token ID on a neg-risk market, the contract call will revert silently and you will spend hours debugging. The docs touch on this but do not flag it as the production gotcha it is.

2. Proxy wallet signing. Polymarket allows you to trade through a Gnosis Safe proxy wallet rather than directly from your EOA (externally-owned account). For bots, this is the right setup — the Safe holds funds and the EOA is just a signer. But the SDK defaults to EOA mode. To use proxy mode you need POLY_SIG_TYPE=2 and POLY_FUNDER=proxy_wallet set in your environment (or the equivalent parameters at client construction). The docs mention proxy support but the configuration to actually use it is buried.

3. Rate limits in the real world. Documented limits hide per-endpoint variation and burst behavior. We rate-limit our own bots conservatively (something like 10 requests/second sustained, 30 burst) and have not seen 429s. If you push past that, expect intermittent rejections. The official docs do not give you these realistic numbers.

4. WebSocket reconnection. The WS streams will drop connections silently, especially through home internet or VPN. You need a heartbeat-based reconnection layer with re-subscription on reconnect. The official docs document the streams but do not address the operational reliability question.

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. Gas relayer abstractions. Polymarket's relayer pays your gas — you do not submit transactions yourself for trades. This is great for usability but means your trade flow does not generate transaction hashes you can grep on Polygonscan in the usual way. To trace fills, use the CLOB API's trade history endpoint, not on-chain logs.

The py-clob-client Library vs Raw HTTP

The py-clob-client Python library handles authentication, request signing, and the most common operations. For 90% of what you want to do, use it.

The 10% case for raw HTTP: - WebSocket subscriptions (the library has WS support but it has historically been less robust than raw websockets library usage). - 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, the signing is the trickiest part. Polymarket uses HMAC-SHA256 with timestamp + path + body as the message. The library wraps this; reimplementing it correctly requires reading the library source. Budget half a day if you go this route.

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, orderbook reads via /book, trade history. You do not need an API key to call these.
• Authenticated trading (API key + wallet signature): Place and cancel orders, read your own positions. Requires the four-tuple (api_key, api_secret, api_passphrase, wallet_private_key) plus correct signing on each request.
• On-chain operations (wallet key directly): Redeeming winning positions, moving funds between wallets. These are not CLOB API calls at all — you build the transaction yourself and sign with the wallet key (or, for proxy wallets, use the Safe's execTransaction).

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 official documentation says 100 requests/second on most endpoints. Our experience over thousands of bot-hours suggests treating that as a soft maximum, not a target:

• Sustained polling: 10 requests/second per process is comfortable across all endpoints. Above that you start seeing intermittent 429s, especially on /book.
• Burst behavior: A burst of 20-30 simultaneous order placements is fine. A burst of 100+ will get rate-limited.
• Per-endpoint variance: /prices-history is more strictly limited than /book. Cache aggressively if you backtest at scale.
• WebSocket vs REST: WebSocket subscriptions do not count against REST rate limits. For market data, prefer WS.

If you build a multi-bot system, give each bot its own API credentials and stagger their poll schedules. Sharing credentials across bots is a recipe for getting all of them rate-limited together.

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": Your USDC balance on the proxy wallet (not your EOA) is below the order's cost. Check the proxy address specifically — your EOA balance is not what the order is drawn against.
• 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 has a minimum order size measured in USDC notional (commonly around $1 worth of shares as of 2026). Below that the order is rejected. Check current minimums on the market metadata before sizing tiny test orders.
• 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.
• Silent revert on redemption: Almost always the neg-risk token ID mismatch described earlier. The on-chain call returns no useful error — it just fails.

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. The fidelity parameter controls the resampling granularity in seconds; 5 gives you 5-second bars, 60 gives you 1-minute bars. Polymarket caps the history length, so for older markets you may only get the recent window.
• /trades?market={token_id}&limit={N} — Recent trades on a market. Useful for measuring realized fills against the orderbook midpoint to calibrate slippage models.
• Market resolution endpoint — Once a market resolves, the metadata includes the winning outcome and the resolution timestamp.

For our own backtests (CS2, NBA, NHL, MLB, NCAAMB, soccer) we use /prices-history with fidelity=5 as the price truth and reconstruct trade decisions against that series. The 5-second granularity matches well to typical in-game decision cadence.

What's Missing From the API Entirely

A few things you might want from the Polymarket API that simply do not exist:

• Historical orderbook snapshots. You can get historical prices but not historical book depth. If you want to measure how slippage would have played out on an old trade, you have to estimate from price changes around the trade time, not from the book.
• 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.
• Detailed fee disclosures per market. The current fee for a market is not always exposed clearly via the API. You have to check the fee documentation and trust that markets behave as the docs describe.

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 credentials, fund your proxy wallet with a small amount of USDC, and place one tiny test order (5 shares at well below the bid so it sits on the book). Cancel it.
5. Place a real order and let it fill. Confirm your fill notification arrives via WebSocket and that your position reflects correctly.
6. Wait for the market to resolve. Redeem your winnings (or accept your loss). Confirm the 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 we've described as "the docs cover poorly," the next move is reading the py-clob-client source code and the Polymarket contracts repo on GitHub. The signing logic, the neg-risk adapter ABI, the proxy wallet integration — these are all in source. The contracts repo specifically is the only place to confirm what the on-chain calls actually do.

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.