Polymarket API Guide: Endpoints, Data & Limits (2026)

TL;DR

• Polymarket exposes three public REST APIs: Gamma (gamma-api.polymarket.com) for events and markets, CLOB (clob.polymarket.com) for order books, prices, and trading, and the Data API (data-api.polymarket.com) for trades, holders, open interest, and leaderboards. The docs' own examples read all of it without an API key.
• Trading is the only part that needs credentials. It uses a two-layer scheme: an EIP-712 wallet signature (L1) that mints API credentials, then HMAC-SHA256 request signing (L2) on every private call.
• Rate limits are published and IP-based, enforced by Cloudflare: for example 4,000 requests per 10 seconds across Gamma, 1,500 per 10 seconds on /book, and 9,000 per 10 seconds across CLOB. Over-limit requests are throttled (queued) rather than instantly rejected.
• For live data, the market WebSocket (wss://ws-subscriptions-clob.polymarket.com/ws/market) streams book, price, and trade events and needs a PING every 10 seconds. Prediction market data from the Data API is now on v2 (v1 is frozen), and a separate PolyBolt socket streams crypto, equity and TWAP prices.

Ever pulled a Polymarket price, thought you were done, and then found the same market has three different "ids", two price fields, and token ids stored as a string that looks like an array? You are not alone, and it is the single most common reason a first Polymarket script returns garbage. The Polymarket API itself is well documented and genuinely developer-friendly. The trick is knowing which of its three services to call, in which order, and which fields to trust.

This guide goes through all of it: the architecture, the endpoints that matter, how authentication actually works, how to stream live data, how orders are built and rejected, and exactly how fast you can call everything.

It covers the Polymarket API docs at docs.polymarket.com. The docs index I checked has no pages for Polymarket US, so nothing here describes that product. For how the two differ, see our guide to Polymarket in the US.

What Is the Polymarket API, and How Is It Structured?

There is no single "Polymarket API". There are several services, each with its own base URL, and the split follows the lifecycle of a market: discover it, read its live state, trade it, then analyze what happened.

Polymarket settles on Polygon (chain id 137), and the order book is a central limit order book (CLOB) matched off-chain and settled on-chain. That hybrid design is why price and book reads feel like a normal exchange API while ownership of positions is still verifiable on-chain. For the structural difference between this model and automated market makers, see order book versus AMM.

Polymarket also publishes machine-readable OpenAPI specs for the Gamma, CLOB, and Data APIs and AsyncAPI specs for its WebSocket channels. If you generate client code, generate it from those specs rather than from this guide, since they update first.

Which Polymarket API Should You Use for What?

The fastest way to avoid wasted work is to match the job to the service.

A useful rule of thumb: Gamma tells you what exists, CLOB tells you what it costs right now, and the Data API tells you what happened.

How Do You Read Markets and Events With the Gamma API?

Gamma is the entry point for almost every project, because it is where you turn a human-readable slug into the identifiers the other services need. It is public and needs no authentication.

What Is the Difference Between an Event and a Market?

An event is a container. A market is a single tradable question inside it. "Who will win the election" is an event; "Will Candidate A win" is one market within it. Multi-outcome events hold many markets, one per candidate or threshold.

This matters for aggregation. If you want one row per tradable contract, query markets. If you want one row per topic, query events and read the nested markets.

How Does Pagination Work on Gamma?

Use the keyset endpoints for anything that walks a large set. GET /events/keyset and GET /markets/keyset return a next_cursor. You pass it back as after_cursor and stop when no next_cursor comes back. Keyset endpoints default to 20 results and cap at 100 per page, and they reject offset with an HTTP 422. Cursor pagination avoids the skipped and duplicated rows that offset pagination produces when markets are created while you are scanning.

The classic GET /markets supports limit and offset plus a long list of filters, including volume_num_min, volume_num_max, liquidity_num_min, end_date_min, end_date_max, tag_id, slug, condition_ids, and closed.

One filter behavior is worth knowing before you hit it. On /markets, passing closed=any removes the open or closed filter, but then requires at least one identifier (id, slug, clob_token_ids, condition_ids, and similar, up to 100 values each). closed=any with only a tag_id returns an HTTP 422. On /events, closed=any needs no identifier.

Which Market Fields Should You Actually Use?

A market object has well over a hundred fields. These are the ones that matter for most data work:

The two gotchas that break most first scripts are in that table. First, outcomes, outcomePrices, and clobTokenIds arrive as JSON-encoded strings, so you have to parse them before indexing. Second, entries at the same index across outcomes and outcomePrices describe the same outcome, and for binary markets index 0 is Yes and index 1 is No.

Always branch on version. Both clobTokenIds and positionIds can be populated on a single market, so the presence of a field does not tell you which protocol applies. Use v1 with clobTokenIds and v2 with positionIds, and treat anything else as unsupported.

How Do You Read Prices and Order Books With the CLOB API?

The CLOB API serves live market state and needs no credentials for reads. Everything is keyed by outcome token, not by market, because each outcome trades as its own asset.

The batch endpoints (/books, /prices, /midpoints, /spreads, /last-trades-prices) accept up to 500 items per request. If you are tracking a few hundred outcomes, batching turns hundreds of calls into one and keeps you far from the rate limits covered below.

What Does a Book Response Contain?

A /book response includes market (the condition id), asset_id, timestamp, hash, bids, asks, min_order_size, tick_size, neg_risk, and last_trade_price. Each ladder entry is a price and a size.

Read the ordering carefully. Bids are sorted ascending and asks descending, which means the best bid and best ask are the last entries in their arrays, not the first. A lot of homemade "best price" code takes index 0 and reports the worst quote on the book.

Two edge cases are worth handling. For a token that has never traded and has an empty book, /last-trade-price returns "0.5" with an empty side. And /last-trades-prices simply omits tokens that have never traded, so a missing key is not an error.

What Does a Price Mean in Probability Terms?

Each outcome token pays $1 if that outcome resolves true and $0 otherwise. A Yes token priced at $0.63 implies a 63% market probability. For a binary market, the Yes and No prices should sum to roughly $1, with any gap reflecting spread. If you are building a probability series, the midpoint is usually a better estimate than the last trade price on thin markets. For the broader pitfalls of treating a price as a clean probability, see why prediction market odds disagree.

How Do You Get Historical Prices From the Polymarket API?

Price history is documented on the Data API as GET /v2/prices-history. Polymarket's market-data docs describe this version, and the CLOB /prices-history endpoint still appears in the rate-limit table, so check the CLOB reference before relying on the older one.

The v2 endpoint takes these parameters:

Use exactly one of interval, start with an optional end, or as_of. The minimum bucket is 600 seconds for max and 1m, and 300 seconds for 1w. The docs show 1d and max in examples and do not give a complete list of interval values, so test the ones you need.

The response puts the points in data, oldest first, each with a timestamp, a price and a resolution_seconds. A pagination object carries has_more and next_cursor.

The identifier is the outcome token, not the condition id or the slug, and passing the wrong one is the most common cause of an empty history. For a full workflow that uses this series, see how to backtest a prediction market strategy.

What Polymarket Data Does the Data API Provide?

The Data API covers what happens around a market after discovery and trading. Version 2 launched on September 4, 2026 at https://data-api.polymarket.com/v2, and v1 is frozen. The v2 surface has 21 GET paths and an OpenAPI document at data-api.polymarket.com/v2/openapi.json.

Every successful response wraps its payload in data. Paginated routes add a pagination object with next_cursor and has_more, and you follow the cursor until it is null. Passing an offset returns a 400. Errors return JSON with error, code, retryable and trace_id, and the trace id is also echoed in the x-trace-id header.

Several limits are worth knowing. /v2/trades and /v2/leaderboard return up to 1,000 rows on the first page. /v2/trades accepts up to 20 values each for condition and event_id. /v2/tokens accepts up to 50 token_id values or up to 10 condition values per call. /v2/holders returns 100 rows per outcome token by default, up to 1,000.

/v2/tokens solves the "I have a token id from a trade, which market is it" problem. Holder data has one subtle behavior: the page size applies per outcome token, not across the whole market, so merge results by asset id rather than assuming one flat list.

The leaderboard route takes time_period (day by default, week, month or all), a category (overall by default), and sort_by (PNL by default, or VOLUME). It is the same ranking you see on Polymarket's website. For what that ranking shows, what it leaves out, and where else to find prediction market data, see our guide to the sources.

How Does Polymarket API Authentication Work?

Reading is open. Trading is not. Private CLOB calls use two layers, and understanding why there are two makes the flow much easier to implement.

What Are L1 and L2 Authentication?

L1 proves you control a wallet. You sign an EIP-712 typed message with your private key, and Polymarket returns a set of API credentials. L2 uses those credentials to sign every subsequent private request with HMAC-SHA256, so your private key is not needed on every call.

The L1 typed data uses the domain ClobAuthDomain, version 1, chain id 137, with a ClobAuth struct holding address, timestamp, nonce, and a fixed message: "This message attests that I control the given wallet". The nonce is 0 unless you manage multiple credential sets for one wallet.

L1 requests carry four headers: POLY_ADDRESS, POLY_SIGNATURE, POLY_TIMESTAMP, and POLY_NONCE.

Either call returns apiKey, secret, and passphrase. The secret is base64-encoded and is the HMAC key.

How Do You Sign an L2 Request?

For each private request:

1. Generate a fresh Unix timestamp in seconds.
2. Build the message from the timestamp, the uppercase HTTP method, and the request path. Query parameters are not part of the signed path.
3. Base64-decode your secret, use it as the key, and compute HMAC-SHA256 over the message.
4. Encode the digest as URL-safe base64 with padding.
5. Send the result in the headers below.

A 401 on a private call usually means a bad signature, an expired timestamp, or the wrong credentials. Use the SDK's signing helpers where you can, and keep your system clock accurate.

Which Wallet Types Does Polymarket Support?

The signer is the key that controls the account. The account wallet is the address that actually holds funds and positions. They are not always the same address.

A deposit wallet owner can give a separate signer scoped, time-limited trading access through session keys. That is the safer pattern for bots: a scoped, expiring key instead of your main private key sitting on a server.

If your account predates the deposit wallet, you are probably on a proxy or Safe wallet, which changes how you configure the signer and funder. Check which type your account is before assuming the defaults apply.

What Is pUSD, and What Does Trading Need?

Trading collateral on Polymarket is pUSD, deployed on Polygon at 0xC011a7E12a19f7B1f670d46F03B03f3342E82DFB, according to Polymarket's contracts page. Older guides, and many third-party tutorials, still say USDC, so treat any code that hardcodes a collateral address from before 2026 with suspicion.

Polymarket's quickstart asks for at least 10 pUSD in an account created or funded at polymarket.com before you place a first order. A market order then fills against available liquidity and any unfilled amount is canceled instead of resting. The trade settles on-chain asynchronously, and the SDK offers a helper to wait for that settlement.

Everything is on Polygon mainnet (chain id 137). The contracts page lists many more, including the collateral adapters, and notes that approving the collateral adapter does not grant the Neg Risk Adapter approvals.

Trading needs token approvals before an account can place orders, and the Data API exposes a /v2/approvals route to read a wallet's current approvals. Use the SDK's setup helpers instead of hand-writing approval transactions, and always confirm addresses against the official contracts page before sending real funds. They are listed here so you know what to look for, not as a substitute for checking.

How Do You Place an Order on the Polymarket CLOB?

An order is built, signed by the wallet, wrapped in an L2-authenticated request, and posted. The SDK does the construction for you, but the rules it enforces are worth knowing because they are the source of nearly every rejection.

What Order Types Are Supported?

Market orders never rest on the book.

A post-only order, set with postOnly: true on a GTC or GTD order, is rejected if it would match immediately instead of resting. This is how market makers guarantee they never accidentally pay taker fees.

What Are the Expiration, Tick Size, and Size Rules?

• GTC orders use an expiration of "0". Market orders must also use "0".
• GTD expiration must be at least 3 minutes in the future, and the stated value is treated as one minute early as a safety margin. For an effective lifetime of N seconds, set the expiration to now + 60 + N.
• Prices must conform to the market's current tick size. Tick size can change, so subscribe to tick_size_change on the market WebSocket rather than caching it forever.
• Each book reports a min_order_size (the example book shows 5 shares), and your rounded share quantity must meet it.

The batch endpoint POST /orders accepts 1 to 15 signed orders per call. A rejected order returns ok: false in the SDK or success: false in the API, with a message explaining why. Cancellation batches are separate: Polymarket's changelog says DELETE /orders accepts up to 1,000 order ids per request since June 15, 2026.

What Do Order Responses and Errors Mean?

Since July 24, 2026, POST /order and POST /orders return tradeIDs instead of transactionHashes on FAK and FOK matches, according to Polymarket's changelog. A successful limit order returns one of these statuses:

Errors come back with an error field, plus HTTP codes that are worth building retry logic around:

The common business-rule rejections are not enough balance / allowance, invalid post-only order: order crosses book, tick-size and minimum-size violations, and order couldn't be fully filled. FOK orders are fully filled or killed. A 503 in post-only mode includes retry_after_seconds and a matching Retry-After header.

What Is the Heartbeat, and Why Does It Cancel Orders?

If you run a market-making bot, the heartbeat matters more than almost anything else on this page. You send a heartbeat every 5 seconds to POST /v1/heartbeats, starting with an empty heartbeat_id and then echoing back the latest id each time. If a valid heartbeat is not received within 10 seconds, all open orders owned by those credentials are cancelled. The check runs every 5 seconds, so cancellation can land up to 5 seconds after the timeout.

This is a deliberate safety feature. It means a crashed or disconnected bot cannot leave stale quotes resting on the book. It also means a bot that forgets the heartbeat will mysteriously lose all its orders.

How Do Polymarket's Fees Appear in the API?

Polymarket charges takers a category-based fee and never charges makers. The fee is computed at match time, so orders themselves carry no fee field.

The formula is fee = C × feeRate × p × (1 - p), where C is shares traded and p is the share price. That curve peaks at a 50-cent price and shrinks toward the extremes.

For 100 shares at $0.50 the taker fee peaks at $1.75 in Crypto, $1.25 in Sports, Economics, Culture, Weather, Combos and the general category, and $1.00 in Finance, Politics, Mentions, and Tech. Geopolitical and world events markets are fee-free, and makers are never charged. On the market object, feesEnabled says whether fees apply, and feeSchedule carries rate, exponent, takerOnly, and rebateRate.

Fee schedules have been revised more than once in 2026, so read them from the market object at trade time instead of hardcoding the table. For the business context behind these numbers, see how Polymarket makes money, and for a cross-platform view, prediction market fees compared.

How Do You Stream Real-Time Data With the Polymarket WebSocket?

Polling is the slow way to build a live dashboard. The market channel pushes changes as they happen, and it is public.

The endpoint is wss://ws-subscriptions-clob.polymarket.com/ws/market. After connecting, send a subscription frame with type set to market and your outcome token ids in an assets_ids array. You can add or remove ids later with an operation field set to subscribe or unsubscribe, with no reconnect.

Set custom_feature_enabled to true to unlock the top-of-book and market lifecycle events. The new_market and market_resolved events are especially useful for aggregators, because they let you discover and close out markets without polling Gamma.

The connection needs a keepalive: send the text frame PING every 10 seconds and expect PONG back. Miss it and the server drops you.

How Do You Track Your Own Orders in Real Time?

The user channel, wss://ws-subscriptions-clob.polymarket.com/ws/user, takes your CLOB credentials in the subscription frame and optionally a markets array of condition ids. Keep those credentials on a server, never in browser code.

Order events carry a type of PLACEMENT, UPDATE, or CANCELLATION. Trade events carry a status that tracks settlement, with values such as MATCHED, MINED, CONFIRMED, RETRYING and FAILED.

Treat only CONFIRMED as settled. The stream does not replay missed events, so after any reconnect, fetch open orders and recent trades over REST first, then apply new stream events on top of that state.

What Is the PolyBolt Price Socket?

Polymarket added a separate socket on September 15, 2026 for reference prices at wss://ws-live-v2.polymarket.com/ws. It serves the price.crypto, price.equity and price.crypto.twap channels, and its channels require authentication: you send an auth message with API credentials, wait for an authed reply, then subscribe with a channel and a symbol filter.

PolyBolt replaces the older RTDS feed for reference prices, which Polymarket now marks as legacy. Live comment and reaction streaming is being retired without a replacement stream, and the docs point to GET /comments on Gamma as a fetch-only alternative. If you use RTDS today, follow Polymarket's RTDS-to-PolyBolt migration guide.

What Are the Polymarket API Rate Limits?

Limits are published, IP-based, and enforced by Cloudflare on sliding windows. When you exceed a limit, requests are throttled (delayed or queued) rather than rejected outright, though a 429 can still occur and should trigger exponential backoff. Trading endpoints also have separate per-signer token-bucket limits.

Trading endpoints carry both burst and sustained ceilings:

How Do You Stay Under the Limits?

Three habits cover almost every case:

1. Batch. Use /books, /prices, and /midpoints (500 tokens per call) instead of looping single-token calls.
2. Stream instead of poll. One WebSocket subscription replaces thousands of /book requests.
3. Cache slow-changing metadata. Market titles, slugs, tags, and token mappings rarely change, so pull them from Gamma once and refresh on a schedule.

Note that these ceilings are shared per IP. If several workers run from one machine or one cloud NAT address, they draw from the same budget.

Which SDKs Does Polymarket Offer?

Polymarket now documents a unified SDK in place of its older split clients. The TypeScript package is @polymarket/client, and the Python package is polymarket-client. A unified Rust SDK is in development, and the docs point to a Rust migration guide for now.

If you find a tutorial importing py-clob-client or @polymarket/clob-client, treat it as pre-V2. Polymarket's changelog says V1 SDKs and orders stopped being supported when CLOB V2 went live on April 28, 2026.

In Python, reads and authenticated trading use separate clients:

• A public client reads markets without any key.
• AsyncSecureClient.create(private_key=...) builds an authenticated client from a private key and your wallet address. The key should come from an environment variable and never be hardcoded.

The quickstart's TypeScript example branches on market.version to pick positionId for v2 markets or tokenId otherwise, which matches the version rule above.

How Do You Fetch a Market's Odds in Practice?

A typical read-only pipeline has four steps, and none of them need a key:

1. Call GET /markets/slug/{slug} on Gamma and read the market object.
2. Parse outcomes, outcomePrices, and the id field that matches version (clobTokenIds for v1, positionIds for v2).
3. Use the Yes outcome's token id with CLOB /midpoint or /book to get a live price, and with Data API /v2/prices-history for the series.
4. Use conditionId against the Data API for trades, holders, and open interest.

Gamma's outcomePrices is convenient but is a snapshot. For anything that drives a decision, such as an alert or an arbitrage signal, read the live book instead, and stream it if latency matters. For a hands-on view of monitoring prices without writing code, see how to track prediction market prices.

What Is Different About Building Across Multiple Prediction Markets?

Everything above applies to Polymarket only. The moment you want to compare odds across venues, you inherit a normalization problem, because every platform defines its own identifiers, price formats, fee models, and resolution rules.

Kalshi, a CFTC-regulated exchange, runs its own REST API with its own schema and authentication, which our Kalshi API guide covers. Limitless, Predict.Fun, and Opinion each have their own contract structures and API conventions. None of the five normalize against each other, so the same real-world event can appear as different markets with different price formats and different resolution criteria. Matching them correctly is a real engineering task, not a join on a title string, which is part of why prediction market arbitrage is harder to execute than to describe.

This is the gap PredictionHero's aggregation layer is built for. It lines up prediction market data from Polymarket, Kalshi, Limitless, Predict.Fun, and Opinion and normalizes the output, so you compare the same event on the same terms instead of reconciling five API responses by hand.

If you are building your own integration anyway, Polymarket is a natural first venue to wire up, because its public read access is open and its documentation is thorough. Read each other platform's API documentation before you commit to a shared schema, and design your internal model around outcomes and probabilities, not around any one venue's field names. If you are new to the platform itself, start with what Polymarket is.

What Should You Check Before You Ship a Polymarket Integration?

A short pre-flight list catches most production problems:

• Parse outcomes, outcomePrices, and clobTokenIds as JSON strings, and branch on version.
• Read the best bid and ask from the last entries of each ladder, not index 0.
• Respect tick size and min_order_size, and listen for tick_size_change.
• Sign the exact request body you send, with a fresh timestamp.
• Send the 5-second heartbeat if you hold resting orders.
• Treat only CONFIRMED trades as settled, and reconcile over REST after every WebSocket reconnect.
• Back off exponentially on 425, 429, 500, and 503.
• Pull fee parameters from the market object, not from a hardcoded table.
• Re-check the docs on a schedule. The SDK and the Data API have both changed recently.

Sources

• Polymarket Documentation. "Rate Limits." docs.polymarket.com
• Polymarket Documentation. "Predictions Changelog." docs.polymarket.com
• Polymarket Documentation. "Real-Time Data." docs.polymarket.com
• Polymarket Documentation. "Real-Time Order Updates." docs.polymarket.com
• Polymarket Documentation. "Prices and Order Books." docs.polymarket.com
• Polymarket Documentation. "Wallets and Authentication." docs.polymarket.com
• Polymarket Documentation. "Place Orders." docs.polymarket.com
• Polymarket Documentation. "Fees." docs.polymarket.com
• Polymarket Documentation. "Error Codes." docs.polymarket.com
• Polymarket Documentation. "Contracts." docs.polymarket.com
• Polymarket Documentation. "SDKs & APIs." docs.polymarket.com
• Polymarket Data API. "v2 OpenAPI specification." data-api.polymarket.com
• Polymarket Documentation. "Gamma OpenAPI specification." docs.polymarket.com

PredictionHero aggregates publicly available prediction market data for informational purposes only. This is not financial advice. Prediction markets may not be available in all jurisdictions.