Understanding Prediction Market APIs: Data Access, REST vs WebSocket, and Normalization
What a prediction market API provides
Prediction market APIs expose data about events, markets, outcomes, prices, trades and resolutions. The data can be accessed through REST endpoints, real‑time streams, or both. This allows developers to discover markets, monitor live activity, and analyse historical information.
Key points
- Discovery routes give event titles, outcome labels, rules, closing times and stable IDs.
- Market‑data routes return current quotes, order books, public trades, price history and volume.
- Account routes (when authenticated) add positions or fills.
- Resolution fields report the market status, result, source and settlement time.
REST endpoints for discovery and recovery
REST calls return a complete snapshot of data at request time. They are best for initial discovery, periodic reconciliation and recovery after a disconnect. For example, Gemini’s documentation frames REST as a discovery and state‑recovery surface.
WebSocket streams for live updates
WebSocket connections stay open and push changes after a subscription. They are useful for receiving live price updates, new trades, market creation messages and resolution events. Polymarket, Kalshi and Manifold each provide WebSocket channels with venue‑specific authentication requirements.
Normalizing quotes, order books and trades
Different venues use different field names. A normalized price record should indicate whether the value is a bid, ask, last trade, midpoint or mark, and include the outcome identifier, size, book time, source event time and local observation time. Order‑book data must keep bids and asks separate and retain timestamps.
Authentication and public vs private data
Public market data usually requires no API key, while trading actions need signed requests. Polymarket’s public data is unauthenticated, but its trading API needs credentials. Kalshi requires signed WebSocket handshakes. Account‑specific data (positions, balances) must be kept separate from public records.
Rate limits, pagination and time handling
Each endpoint may have its own rate limits and pagination rules. Polymarket publishes limits by API family; Kalshi advises exponential backoff after HTTP 429. Use opaque cursors for pagination and convert all timestamps to UTC milliseconds while retaining the raw source value.
Recovering from disconnects and schema changes
If a stream gaps, a heartbeat is missed, or a schema changes, stop applying deltas. Fetch a fresh REST snapshot, replace the affected state and resume from the venue’s documented boundary. Do not guess missing updates.
