The Polymarket API for Traders: Data API, CLOB and WebSockets

Polymarket exposes several APIs, but two do most of the work for traders. The CLOB API at https://clob.polymarket.com handles prices, order books and order placement. The Data API at https://data-api.polymarket.com/v2 handles positions, profit and loss, activity and leaderboards. A third surface, the Gamma API at https://gamma-api.polymarket.com, is the catalogue of events and markets. Public reads need no key. Trading needs a wallet signature and HMAC credentials.

Pick by question. "What does the book look like, and how do I trade it?" is the CLOB. "What does this wallet hold, and what did it do?" is the Data API. "What markets exist?" is Gamma.

Four surfaces, four jobs

Gamma returns events, markets, tags and metadata. It is where you resolve a market slug into the identifiers you need: the condition ID, the outcome token IDs, the tick size and the minimum order size.

CLOB is the trading venue. It serves the order book, best bid and ask, midpoint, last trade, price history, open orders, trades, rewards and rebates. It is also where you sign and submit orders.

Data API v2 is the analytics layer. It covers wallet positions, PnL, activity, holders, open interest, volume and leaderboards. It requires no authentication, uses cursor pagination, and wraps every response in a data envelope with a pagination object.

Relayer submits wallet transactions without requiring the account to hold POL for gas. It is the plumbing behind gasless approvals and position management, not a market-data service.

The CLOB is the authoritative book; the Data API is a derived view. If the two disagree during a fast market, trust the book for execution and the Data API for history.

A public-data workflow

A typical analytics job looks like this. First, find the event or market in Gamma and record the outcome token ID. Second, call the CLOB book endpoint with that token ID to get bids, asks, min_order_size, tick_size and the negative-risk flag. Third, pull price history for the token. Fourth, pull the wallet's positions from the Data API. Fifth, pull its activity feed to see how the position was built.

The Data API's position rows are useful because they separate entry cost, current value, realized PnL and unrealized PnL. Suppose a wallet holds 10,000 YES shares with an average entry price of $0.40 and the current mark is $0.55. The entry cost is $4,000, the current value is $5,500, and the unrealized gain is $1,500, or 37.5% on cost. If the same wallet had sold 2,000 shares at $0.50 earlier, that leg would show a realized gain of $200 separately. The two numbers answer different questions: one is money already banked, the other is a mark that can disappear.

Data API v2 uses cursor pagination, not offsets. Send the first request with a limit, read pagination.next_cursor, and resend with cursor until it is null. Keep the same filters on every page: the cursor carries a seek anchor, not the full query, so changing a filter mid-walk silently changes the result set. Amounts are JSON numbers, fields suffixed _usdc are dollar amounts, and bare volume or size values are shares. A missing numeric field means unavailable, not zero.

Authenticated trading

CLOB authentication has two layers. L1 is a wallet signature over an EIP-712 ClobAuth message. It proves you control the signer address and lets you create or derive API credentials. L2 is HMAC-SHA256 over the timestamp, HTTP method, route path and exact serialized body. The request carries five headers: POLY_ADDRESS, POLY_SIGNATURE, POLY_TIMESTAMP, POLY_API_KEY and POLY_PASSPHRASE.

The order itself is a separate EIP-712 signature over the exchange's order struct. That signature authorizes the price, size, token and expiration; the L2 headers authenticate the HTTP request. Both are required. A common integration bug is to sign the order correctly but serialize the request body differently from the bytes used to compute the HMAC, which produces a valid-looking request that the server rejects.

Treat the API secret as a bearer credential. Anyone who has it can submit authenticated requests, including cancellations, within the permissions of the credential. Keep it server-side, rotate it if it leaks, and use a scoped session key where the wallet supports one. A frontend that ships the secret to the browser is not a secure design, even if placing an order still requires a wallet signature.

Order responses need careful reading. A successful submission returns a status of live, matched, delayed or unmatched. Live means resting. Matched means it executed immediately. Delayed means it was accepted but is waiting out a market's matching delay. Unmatched means a marketable order ended up on the book without a match. After matching, trades move through MATCHED, MINED and CONFIRMED, with RETRYING and FAILED as the failure paths. An HTTP 200 is not the same as a fill.

Rate limits and streams

Cloudflare enforces IP-based limits, and they are generous but not infinite. The CLOB's general limit is 9,000 requests per 10 seconds; the book endpoint is 1,500 per 10 seconds; price and midpoint are each 1,500. Order placement has a burst limit of 5,000 requests per 10 seconds and a sustained limit of 120,000 per 10 minutes. The Data API v2 general limit is 800 per 10 seconds, with trades at 300 and positions at 200. Gamma's markets endpoint is 300 per 10 seconds.

Separately, order and cancel requests use per-signer token buckets. The Standard tier allows 40 order tokens per second with a burst of 60; Gold, at $500,000 of 30-day volume, allows 400 per second with a burst of 600; Elite, at $10 million, allows 600 per second with a burst of 900. A batch costs one token per order and is admitted all-or-nothing, so a batch larger than the burst capacity can never succeed as one request. When throttled, read Retry-After and back off rather than retrying immediately.

For real-time data, use WebSockets instead of polling. The market channel at wss://ws-subscriptions-clob.polymarket.com/ws/market streams book snapshots, price changes, last trade prices and tick size changes. The user channel at wss://ws-subscriptions-clob.polymarket.com/ws/user streams authenticated order and trade updates. RTDS at wss://ws-live-data.polymarket.com covers reference prices, comments and trade activity, and a separate sports channel covers live game status and scores.

The standard pattern is snapshot plus deltas: fetch the REST book once, subscribe to the market channel, apply updates in order, and resync from REST after any reconnect or sequence gap. Do not assume the stream is a complete history.

Practical use cases

• Copy-trading analytics. Poll the Data API activity feed for a set of wallets, deduplicate by transaction hash, and measure the delay between the tracked trade and your detection. Execution goes through the CLOB, subject to per-signer limits.
• Market making. Maintain a local book from the websocket, quote both sides with post-only orders, batch up to 15 orders per request, and cancel-and-replace when fair value moves.
• Backtesting. Pull price history from the CLOB. Its price-history store keeps raw one-minute data for at least seven days, five-minute data for at least 60 days and thirty-minute data for at least 90 days; the twelve-hour series is permanent. A one-minute request over a one-year window is an incompatible pair, not an empty market.
• Risk dashboards. Combine positions, open orders, rewards and rebates in one view. Reconcile the Data API's marks against the CLOB's live book before acting.

Where automation breaks

The failures are rarely dramatic. A 429 arrives during a volatility spike. A websocket reconnects and the local book is one update behind. A market's tick size changes and a previously valid price is rejected. A wallet is in a close-only jurisdiction, so orders are rejected even though reads work. A Data API field is null, and code that treats null as zero reports a fake loss. An API version changes, and a v1 route that worked last month now returns a deprecation error.

Build for those cases explicitly: backoff with jitter, sequence checks, a REST resync path, validation against the market's current tick and minimum size, a geoblock check at startup, and a hard kill switch that cancels all orders. The API is fast enough to automate. It is not forgiving enough to automate carelessly.