Polymarket API Guide: Live Markets, WebSockets and Historical Research

Map the task to the data surface

Polymarket API key and pricing: public data versus trading

Polymarket's current documentation says its Gamma API, Data API, and public CLOB read endpoints for books, prices, midpoints and spreads do not require an API key, authentication or a wallet. If the task is only to discover markets or read current market data, start with those public endpoints rather than creating trading credentials.

Authenticated CLOB trading is a different workflow. It uses wallet-signed L1 authentication to create or derive L2 API credentials, then signed headers for orders and account operations. Do not place a wallet private key or CLOB secret in browser code. Public market-data access and trading credentials should not be described as one pricing or authentication tier.

DepthFeed is a separate historical-data service with its own key and plans. Its value is retained full-depth observations, normalized cross-venue research fields and replay tools; it is not a paid key for Polymarket's public API.

Why identifiers and timestamps come first

A Polymarket integration crosses event, market, condition and token identifiers. Store those relationships with the raw source values instead of treating a human-readable title as a key. A title can change; an execution study must still join the same outcome token to the same recorded book.

Keep source timestamps and receive timestamps separately. The source time describes the venue event, while receive time describes when your system observed it. Collapsing them into one field makes latency and ordering errors impossible to audit.

What DepthFeed adds

DepthFeed records event-driven Polymarket CLOB updates, builds normalized full-book observations and serves them through the same REST and WebSocket shapes used for Kalshi. Historical rows include price and size ladders rather than only a single probability point.

That record supports depth-aware VWAP replay in the Backtest Lab, historical API queries and next-book execution audits for public wallet activity. Missing coverage remains explicit, and the archive does not claim to reproduce hidden liquidity, queue priority or a real order's market impact.

Integration checklist

• Use official Polymarket docs as the authority for current endpoints and trading rules.
• Persist event, condition and outcome-token identifiers together.
• Seed a complete book before applying incremental price changes.
• Keep source and receive timestamps instead of overwriting one with the other.
• Use price history for charts and full historical ladders for execution replay.
• Test gaps, reconnects and duplicate updates before trusting a backtest.

Polymarket API objects and identifiers

A robust Polymarket data model keeps the event, market or condition, outcome, and CLOB token identifiers as separate columns. The event groups related propositions for presentation. The market or condition describes the binary contract and resolution context. Outcome tokens identify the order books that actually carry bids and asks. Collapsing these into a title string makes later joins fragile.

Store the original identifiers and labels even if the application creates a normalized market key. That preserves a route back to the official contract, lets you audit outcome ordering, and prevents title edits from creating a false new market. It also makes delisting, resolution and merged event displays easier to handle without rewriting historical rows.

Live Polymarket order-book reconstruction

Treat a complete book as state and incremental messages as mutations to that state. Initialize every subscribed token from a documented snapshot or full-book message. Apply updates only after the seed is known, remove levels whose size becomes zero, and keep bids and asks sorted in opposite directions. A reconnect or sequence uncertainty should invalidate the local state until it is seeded again.

Measure two clocks when possible: the source event time and the time your collector received or persisted the message. The difference does not equal exchange latency by itself, but it makes ordering, network delay and processing stalls observable. A single overwritten timestamp destroys that diagnostic evidence.

Price history versus historical depth

A historical price endpoint is useful for probability charts, returns, broad volatility and signal prototyping. It does not reveal the bid-ask spread, quantity available at the touch, deeper liquidity or whether a sized order would have completed. Those facts disappear when the live ladder changes.

For execution-aware research, persist complete or reconstructable books prospectively. At decision time, a buy should walk asks and a sell should walk bids. Report the resulting VWAP, partial fill or rejection. Keep midpoint fills only as an explicitly optimistic benchmark, not as the default representation of executable performance.

A production-ready Polymarket ingestion pipeline

• Discover current events and markets, then persist their official identifiers and resolution metadata.
• Resolve each tracked outcome to the correct CLOB token before subscribing.
• Seed a full book, apply incremental changes deterministically and reseed after uncertainty.
• Write raw source events to an append-only lane before producing normalized complete-book observations.
• Validate price bounds, matching price-size lengths, side ordering and crossed-book conditions.
• Partition retained history by date and stable market key, with a schema version and gap log.
• Expose both the native Polymarket fields and a normalized cross-venue representation.

curl -s "https://api.depthfeed.com/v3/btc/markets?limit=5" \
  -H "Authorization: Bearer df_your_key"

curl -s "https://api.depthfeed.com/v3/btc/markets/<market_id>/snapshots?include_orderbook=true&interval=1m" \
  -H "Authorization: Bearer df_your_key"

Common Polymarket API failure modes