Polymarket API: The Complete Guide for Developers (2026)

The Polymarket API is the most-used developer surface in prediction markets, and in 2026 it is also the most changed. The CLOB V2 cutover in April rewrote the exchange backend, wiped every open V1 order, replaced the collateral token, and killed the old SDKs. Most tutorials you will find were written before that date, and their code silently fails against production today.

This guide covers the API as it actually works now: the four services and what each is for, reading market data and history for free, WebSocket streaming, the V2 auth and order-signing model, the current SDK lineup, and the separate Polymarket US exchange. It was rechecked on 9 August 2026 against Polymarket's official documentation and package registries, and the Python SDK had already shipped a new minor version in the days since the first draft, which tells you what kind of target this is. Nothing here is legal, tax, or financial advice.

The Polymarket API Is Really Four APIs

They share a brand and very little else, and knowing which one answers which question saves hours:

The workflow that follows from this split: discover markets and grab token IDs from Gamma, read live prices and books from the CLOB, stream updates over WebSocket, and check wallet-level history through the Data API.

The 2026 Reality Check: CLOB V2

On April 28, 2026, Polymarket cut over to CLOB V2: new exchange contracts, a rewritten matching backend, and a new collateral token. Every open V1 order was wiped at the cutover, there is no backward compatibility, and the V1 infrastructure was fully retired at the end of June after a forced migration window. Two things from that cutover still break code today, and a quieter change landed in July that catches the people who migrated early.

Order signing. Orders are EIP-712 signed against the "Polymarket CTF Exchange" domain at version 2. The V2 order struct dropped the old nonce, taker, and fee-rate fields and added timestamp, metadata, and a builder field that attributes order flow to the app that produced it. Any sample code signing domain version 1 fails silently.

Collateral. Trading collateral is now pUSD, an ERC-20 on Polygon with 6 decimals, backed 1:1 by USDC, and it replaced USDC.e at the cutover. Deposits convert into it automatically, so there is no manual wrapping step to forget. The read side is what bites: a balance check written against USDC, or against the old USDC.e, comes back zero, so a bot with money in the wallet decides it has none. If funding looks right and orders still fail, check which token you are querying before you go anywhere near the signing code.

The July change is easy to miss because nothing about it looks broken. Since 24 July 2026, POST /order and POST /orders stopped returning transactionHashes on a successful FAK or FOK match and hand back tradeIDs instead, which you poll to recover the hashes. Code that read the hash straight off the order response now reads nothing at all. Polymarket's predictions changelog is where this class of change surfaces first, and it is worth a standing reminder rather than a quarterly panic.

Reading Market Data for Free

Discovery starts at Gamma. List active events, search by slug, and pull each market's clobTokenIds, the long decimal token IDs that every CLOB call uses:

curl "https://gamma-api.polymarket.com/events?active=true&closed=false&limit=10"

With a token ID in hand, the CLOB gives you live trading data:

curl "https://clob.polymarket.com/book?token_id=TOKEN_ID"
curl "https://clob.polymarket.com/price?token_id=TOKEN_ID&side=BUY"

Both have batch variants, which is how you avoid hammering the endpoint once you are watching more than a handful of markets. The cap was 500 tokens per request at the time of writing, and the endpoint pages in Polymarket's docs carry the current figure.

Price history comes from GET /prices-history with intervals of 1h, 6h, 1d, 1w, 1m, or max, plus a fidelity parameter in minutes, returned as simple timestamp-and-price points. One gotcha worth designing around: once a market resolves, the endpoint only serves coarse 12-hour granularity, so pull fine-grained history from markets you care about before they close.

A vocabulary note that prevents a whole category of bugs: the condition ID identifies a market, while each outcome has its own token ID. CLOB price, book, and streaming calls take token IDs; user-channel subscriptions and settlement operations use condition IDs. Mixing them up produces empty responses rather than errors.

WebSocket Streaming

The market channel at wss://ws-subscriptions-clob.polymarket.com/ws/market is public, no key required. Subscribe by sending the asset IDs you want:

{"type": "market", "assets_ids": ["TOKEN_ID"], "custom_feature_enabled": true}

You receive book, price_change, last_trade_price, and tick_size_change events, and with the custom feature flag also best_bid_ask, new_market, and market_resolved. Send a PING every 10 seconds to keep the connection alive.

The user channel at /ws/user requires your API credentials and streams your own order lifecycle (placement, update, cancellation) and trade status as it moves from matched to mined to confirmed. Trading systems want both channels: market for the world, user for your own state.

Trading: Auth and Order Signing

Polymarket's auth has two layers, and the names confuse everyone once. L1 is your wallet: an EIP-712 signature proves you control the address and derives your API credentials, a one-time setup step. L2 is those derived credentials (key, secret, passphrase) signing each API request. Orders themselves are additionally EIP-712 signed against the V2 exchange domain, which means your private key never leaves your machine and funds stay in your own wallet. That self-custody model is the fundamental difference from account-based exchanges like Kalshi.

Supported order types are GTC, FOK, and FAK (plus time-bound orders), and multi-outcome negRisk markets carry a flag that must be passed when placing orders against them; omitting it gets orders rejected. Redemption code copied from older repositories is a related trap: relayer redeems aimed at the previous Neg Risk Adapter address were retired on 17 July 2026, so a script still pointing there fails outright.

Rate limits exist and are generous for reads, but published numbers vary between sources and have changed during 2026, so treat any specific figure as subject to change and watch the rate-limit response headers in production.

The SDK Lineup

Three generations are in circulation and only one of them is the right answer. The original py-clob-client, which nearly every pre-2026 tutorial imports, targets the V1 exchange and sits in an archived repository whose README tells you to leave. The cutover-era V2 clients, py-clob-client-v2 on PyPI and @polymarket/clob-client-v2 on npm, still function but have been superseded. New work belongs on the unified SDKs: polymarket-client for Python and @polymarket/client for TypeScript. Polymarket's own documentation opens its examples with import { createPublicClient } from "@polymarket/client", which is a fair signal of where the vendor's attention sits.

pip install polymarket-client     # then: import polymarket
npm install @polymarket/client

Two things about the Python package catch people. The install name and the import name differ, as above, and it wants Python 3.11 or newer. It also moves fast: it sat at 0.4.0 in the first days of August 2026 and 0.5.0 by the 7th, so read its PyPI page for the current release before you pin a version, and take order-placement call signatures from Polymarket's trading quickstart rather than from any article, this one included. We have deliberately stopped reproducing a full signed-order snippet here for that reason: a code block that goes stale in a fortnight is worse than a link that does not.

One line to delete on sight wherever you inherit it: client.set_api_creds(client.create_or_derive_api_creds()). Both current generations derive credentials during client construction, so that call is a V1 leftover. An official Rust client also exists for systems traders.

Polymarket US Is a Different API Entirely

The CFTC-regulated Polymarket US exchange runs on a separate entity's licence, QCX LLC, and has its own stack; none of the above applies to it. Its waitlist came off on 19 May 2026, so it takes ordinary signups now. At the time of writing the base URL is api.polymarket.us/v1, authentication is Ed25519 signatures with keys issued after KYC in the US app, markets are addressed by slug rather than token ID, prices are plain USD values, and there are no wallets or EIP-712 anywhere. Dedicated polymarket-us SDKs exist for Python and TypeScript. It also publishes its own fee schedule, which has nothing to do with the global platform's, so docs.polymarket.us is the source for both the endpoints and the costs. If you serve US users, treat it as a separate integration with a separate code path, not a configuration flag on your global Polymarket code.

Access is a code problem as much as a legal one. The global platform's restricted-jurisdictions list has passed 30 countries, the UK and Singapore among them, and the docs expose a geoblock endpoint that checks the eligibility of a requesting IP, so your integration can find out before your users do. Four Canadian provinces, Ontario, Alberta, British Columbia and Quebec, are listed there as close-only, meaning existing positions can be exited but new ones cannot be opened. A 2022 CFTC settlement is the reason US residents belong on the US exchange rather than the global one. None of that is legal advice, and an API key is not a permission slip: read the terms of service, and our breakdown of where Polymarket is legal, before pointing a bot at either venue.

Frequently Asked Questions

Conclusion

The Polymarket API earns its popularity: no other prediction market gives you this much data, including live streams, without so much as an API key. The 2026 rule is to distrust anything written before April 28, and to skim the changelog before you ship rather than after something breaks. Verify the SDK you install is current-generation, sign against the V2 domain, read balances in pUSD rather than USDC, and keep the condition-ID versus token-ID distinction straight, and the integration is one of the smoothest in the space.

For how Polymarket compares to the rest of the landscape, see our ranking of the 7 best prediction market APIs and SDKs in 2026. Coming from the regulated side instead, our Kalshi API guide covers the other major venue in the same depth. And if you are brand new to this space, start with what a prediction market API is.