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. Everything here was verified in August 2026 against Polymarket's official repositories and documentation.

The Four APIs of Polymarket

"The Polymarket API" is actually several services, 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. Three consequences matter for anyone writing code today:

First, order signing changed. 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.

Second, collateral changed. Trading collateral is now pUSD, an ERC-20 on Polygon backed 1:1 by USDC. The frontend migrated users automatically; API traders must wrap USDC into pUSD themselves through the collateral onramp contract before their first V2 order. If your bot funds look right in the wallet but orders fail, this is the first thing to check.

Third, the SDK generations moved fast. More on this below, but the headline is that even the V2 clients released at cutover now point new projects to a newer unified SDK.

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, with batch variants that accept up to 500 tokens per request:

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

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.

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

Polymarket shipped two SDK generations in three months, so choose deliberately. The V2 CLOB clients, @polymarket/clob-client-v2 on npm and py-clob-client-v2 on PyPI, were released for the cutover and work today. But both now recommend the newer unified SDKs for new projects: @polymarket/client for TypeScript and polymarket-client for Python, which combine REST and WebSockets in one package. Starting fresh, use the unified SDKs; maintaining a cutover-era integration, the V2 clients remain supported.

The core flow looks the same in either generation. In Python with the V2 client:

from py_clob_client_v2.client import ClobClient
from py_clob_client_v2.clob_types import OrderArgs
from py_clob_client_v2.order_builder.constants import BUY

client = ClobClient(host, chain_id=137, key=private_key)
client.set_api_creds(client.create_or_derive_api_creds())

order = client.create_and_post_order(OrderArgs(
    token_id="TOKEN_ID", price=0.40, side=BUY, size=100
))

An official Rust client also exists for systems traders.

Polymarket US Is a Different API Entirely

The CFTC-regulated Polymarket US exchange has its own stack, and none of the above applies to it. 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. 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.

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 simply to distrust anything written before April 28. Verify the SDK you install is current-generation, sign against the V2 domain, wrap your collateral into pUSD before trading, 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.