Polymarket API Documentation: Key Endpoints, Latency Concerns and Data Design for Product Teams

Polymarket’s API documentation gives you everything you need to build prediction‑market apps—from market discovery to live order books—but it’s venue‑specific, fragmented across several APIs, and tightly rate‑limited. For most product teams, the winning pattern is: use Polymarket’s native APIs for trading and account state, and a normalization layer like Codex for cross‑venue analytics, odds, and charts.

This guide breaks down the core concepts in the Polymarket API docs (market schema, resolution data, streaming updates), then shows how to turn them into concrete data models—either directly or via Codex’s prediction‑market API.

Polymarket API Documentation at a Glance

Polymarket splits its surface into several distinct APIs, each with its own rate limits and data shapes:

• Gamma API – market and event discovery, metadata
• CLOB API – central limit order book, prices, trades, and trading endpoints
• Data API v2 – account activity, positions, history
• WebSocket APIs – real‑time streaming for books, prices, orders, and trades

From a product‑design perspective, you should think in three logical groups:

1. Market schema: how events, markets, and outcomes are modeled
2. Resolution data: how and when a market becomes final
3. Streaming updates: how you keep a UI fresh without rate‑limit pain

The sections below map each of these to practical data models—and then show how Codex can normalize them across Polymarket, Kalshi, and future venues.

Polymarket Market Schema: Event → Market → Outcome

The most important concept in the Polymarket API docs is the structured relationship between events, markets, and outcome tokens.

Core Polymarket market schema

The docs define a hierarchy:

• Event

  • A real‑world question, e.g. “Will BTC trade above $100k by Dec 31, 2026?”
  • Can contain one or many markets
  • Acts as the umbrella for rules, category, and narrative

• Market

  • A specific tradable contract under an event
  • Single‑market events: 1:1 with the main question
  • Multi‑market events: a group of mutually exclusive markets (often negative‑risk)

• Outcome tokens

  • The tokens representing Yes/No (or more complex outcomes)
  • Prices on these tokens encode implied probability

In multi‑market events, Polymarket highlights negative‑risk groups: exactly one market resolves Yes, the rest No. This is important for:

• Capital efficiency (traders can construct low‑risk portfolios)
• UX (you must display that only one outcome can win)
• Risk modeling (P&L and exposure analytics)

How to model this in your own schema

If you are building directly on the Polymarket APIs, you’ll want explicit objects for each layer:

• Event

  • id
  • title
  • description
  • category / tags
  • startTime, endTime
  • rules (raw text, plus a normalized form if you can)
  • markets: Market[]

• Market

  • id
  • eventId
  • name / shortName
  • negativeRiskGroupId (if applicable)
  • status (open, paused, resolved, cancelled)
  • orderBook (if you ingest CLOB data)
  • outcomes: Outcome[]

• Outcome

  • id
  • marketId
  • label (Yes/No or specific outcome)
  • lastTradedPrice
  • bestBid, bestAsk
  • impliedProbability (derived as price / 1 for Yes/No markets)

Polymarket’s Gamma + Data API v2 give you the raw fields. You’ll often have to:

• Join across endpoints
• Re‑shape response envelopes
• Infer relationships (e.g., grouping markets into negative‑risk sets)

How Codex normalizes the prediction market API schema

Codex’s prediction‑market layer is designed as a cross‑venue schema that already encodes these concepts. A single GraphQL‑style query can give you event → markets → outcomes in a normalized format across Polymarket and Kalshi.

Codex typically exposes primitives like:

• PredictionEvent

  • Unified representation of an event across venues
  • Includes title, description, resolution rules, categories, and lifecycle state

• PredictionMarket

  • Markets grouped under the event, including negative‑risk flags
  • Venue‑agnostic IDs + venue‑specific IDs

• PredictionOutcome

  • Outcome label (Yes/No, candidate names, ranges)
  • Normalized probability (0–1) and price series

You can then query odds consistently, for example:

• "Give me all US election markets above 60% probability across Polymarket and Kalshi."
• "Show top‑trending events in the last 24h by volume and open interest."

Codex has already done the work of ingesting Polymarket’s market schema, resolving relationships, and normalizing outcome probabilities.

Polymarket Resolution Data: Rules, Proposed Resolution, and Final State

Polymarket’s documentation is clear: resolution is not just a Boolean flag. It’s a lifecycle.

How Polymarket resolution works

Key aspects from the docs:

• Rules

  • Each event has human‑readable rules describing what counts as Yes/No
  • Many edge cases are resolved based on this text, not just dates

• UMA Optimistic Oracle

  • Resolution is handled via UMA’s Oracle
  • There is a dispute/challenge process
  • Proposed resolutions can be contested, delaying finality

• Resolution state endpoints

  • Expose both the current lifecycle state and the terminal outcome when final
  • Apps must not infer finality from endTime alone

This implies you need at least three distinct resolution concepts in your data model:

1. Rules (definition)
2. Proposed resolution (in‑flight, subject to dispute)
3. Final resolution (irreversible outcome)

A practical resolution data model

For a solid internal schema, treat resolution as its own object:

• ResolutionRules

  • eventId
  • rulesText
  • source (Polymarket, UMA)
  • lastUpdatedAt

• ResolutionState

  • eventId
  • status (unresolved, proposed, challenged, resolved, cancelled)
  • proposedOutcome (if any)
  • finalOutcome (if status = resolved)
  • resolvedAt
  • disputeHistory: Dispute[]

• Dispute

  • id
  • eventId
  • raisedAt
  • reason
  • status (open, rejected, accepted)

Polymarket’s native endpoints give you the raw fields, but not in this normalized form. You will need to:

• Read the resolution concepts section carefully
• Map UMA‑specific states into your own status enum
• Preserve rules text and links to the oracle

Codex and prediction market resolution events

Codex abstracts much of this into unified fields across venues:

• resolutionStatus (unresolved, resolving, resolved)
• resolvedOutcome (normalized to outcome IDs/probabilities)
• resolvedAt
• A venue‑agnostic rules object

For Polymarket, Codex encodes the UMA lifecycle; for Kalshi, Codex encodes the exchange’s own procedures. Your app can:

• Render consistent resolution badges across venues
• Filter by “only fully resolved events” without venue‑specific if/else
• Run analytics on resolution accuracy and time to finality across multiple platforms

This is precisely where a cross‑venue layer adds value. You no longer need to understand UMA vs. Kalshi vs. future venue‑specific concepts just to show whether a market is final.

Polymarket Streaming Updates: WebSockets and Rate‑Limit Discipline

Polymarket emphasizes streaming to avoid excessive polling on REST endpoints. The docs define multiple WebSocket streams.

Key WebSocket channels in Polymarket API docs

• Market data stream

  • Emits: book, price_change, last_trade_price, tick_size_change
  • Designed for real‑time quotes and order‑book‑driven UIs

• Authenticated user stream

  • Emits: order, trade events for a specific user
  • Used for portfolio updates, fills, and order status

Operational details matter for reliability:

• Server sends a ping every ~25 seconds
• Missing two pongs triggers disconnect with code 4002
• Other codes: 4001 (auth failure), 4003 (draining), 4008 (policy violation)

Your client must:

• Respond to pings quickly and reliably
• Implement reconnect logic with backoff
• Re‑sync state after reconnect (via REST or a snapshot endpoint)

Polymarket REST endpoints and rate limits

Polymarket sets endpoint‑specific rate limits, enforced via Cloudflare. Docs highlight, for example:

• Gamma markets: ~300 requests / 10s
• Data API v2: ~800 requests / 10s
• CLOB /book and /price: ~1,500 requests / 10s
• CLOB /trades: ~900 requests / 10s

Trading endpoints also use per‑signer token buckets, with batches enforced atomically. The docs encourage client‑side queuing and backoff.

You should design your architecture as:

1. Initial snapshot via REST (markets, books, positions)
2. Real‑time updates via WebSockets (prices, books, user trades)
3. Periodic reconciliation to handle missed messages or reconnects

Polymarket’s own changelog notes latency constraints on the trading path, such as a crypto taker delay of 150ms (as of 4 Sept 2026). That’s small for most UIs but relevant for HFT‑style strategies.

How Codex handles prediction market streaming updates

Codex follows the same hybrid pattern but at a cross‑venue level:

• Snapshot APIs for events, markets, odds, and stats
• Subscriptions / streaming for:
  • Live prices and implied probabilities
  • OHLC bars and volume over time
  • Windowed stats (5m, 1h, 4h, 12h, 24h, 1w)

Because Codex aggregates and normalizes feeds from Polymarket, Kalshi, and others, your app can:

• Maintain one streaming integration instead of several
• Use a single reconnection and backoff strategy
• Rely on Codex’s infra (built for 1,000+ req/s and sub‑second latency) instead of managing multiple venue‑specific rate schemes

The trade‑off is clear:

• Use Polymarket WebSockets when you care about per‑user orders or direct trading.
• Use Codex streaming when you care about cross‑venue odds, charts, and analytics.

Prediction Market API Schema: From Venue‑Specific to Unified

Polymarket is one venue. The broader ecosystem now includes Kalshi and other platforms, and the data is not schematized the same way.

Why normalization matters

Dune and Keyrock’s 2025 report shows prediction markets exploding:

• Monthly notional volume: under $100M → $13B+ (early 2024 to Nov 2025)
• Monthly transactions: 43M+
• Monthly users: 600K+
• Open interest: $500M+

Prediction markets are being treated as financial‑market infrastructure, with metrics like Brier score (0.09) and Polymarket accuracy (90–95%) used as quality benchmarks.

If you’re building a professional‑grade product—dashboards, trading apps, or risk tools—you need:

• Consistent event → market → outcome modeling
• Unified probabilities, odds, and price histories
• Venue‑agnostic liquidity, volume, and open‑interest stats

Codex as the prediction market normalization layer

Codex’s prediction‑market API is designed exactly for this:

• One schema across Polymarket, Kalshi, and future venues
• Unified objects for:
  • Events
  • Markets
  • Outcomes
  • Trades
  • Trader analytics (where available, e.g. Polymarket only)
• Built‑in analytics primitives:
  • Aggregated volume and liquidity
  • Windowed stats: 5m, 1h, 4h, 12h, 24h, 1w
  • OHLC bars for prices and probabilities

Codex gives you a prediction market odds API that returns normalized probabilities and prices regardless of venue. Example use cases:

• "Top 20 events by 24h volume across all venues."
• "Events where Polymarket vs Kalshi implied probabilities differ by >10%."
• "Trader leaderboards by P&L on Polymarket (Kalshi doesn’t expose trader data, but Codex handles that asymmetry)."

For a deeper dive into the Polymarket‑specific side (Gamma, CLOB, Data v2), see this related guide: Polymarket API & Gamma Data: What Builders Get and How to Use It in Apps.

Latency, Throughput, and Architecture: Where Codex Fits

Venue‑native APIs are optimized for execution, not for being your all‑purpose analytics backend. For high‑traffic consumer apps, that matters.

Polymarket API latency and throughput constraints

From the docs and rate‑limit tables:

• REST endpoints (Gamma, Data v2, CLOB) are capped at specific requests / 10 seconds
• WebSockets require careful ping/pong and reconnection logic
• Trading latency is bounded by mechanisms like the 150ms crypto taker delay

If you try to run a high‑traffic analytics site, portfolio tracker, or multi‑venue frontend directly on Polymarket’s REST endpoints, you will:

• Hit rate limits quickly
• Need a local cache or database
• Implement complex ETL pipelines to maintain historical data and chart series

Codex performance posture

Codex is built as infrastructure‑grade on‑chain data:

• Sub‑second latency on its token and prediction‑market API
• Designed for 1,000+ requests per second for read‑heavy workloads
• Powers products like Coinbase, TradingView, Uniswap, Magic Eden, Rainbow, MoonPay, and more for token data

For prediction markets specifically, Codex:

• Ingests and enriches native venue feeds (including Polymarket)
• Maintains historical OHLC, volume, and liquidity series
• Offers windowed stats and trending scores

You get trading‑grade analytics without building your own ETL or hitting venue rate limits.

Practical Design Patterns for Product Teams

Bringing it all together, here are practical architectures you can adopt.

1. Trading‑first Polymarket app (single venue)

• Use Polymarket Gamma API for market discovery and metadata
• Use CLOB REST + WebSockets for:
  • Order books
  • Trades
  • Placing/cancelling orders
• Implement your own DB for:
  • Market schema (event/market/outcome)
  • Resolution state and rules
  • Historical prices and volume (if needed)

Best for:

• Venue‑specific trading terminals
• Bots that only trade on Polymarket

2. Analytics‑first, cross‑venue app

• Use Codex prediction‑market API for:
  • Event/market/outcome schema
  • Normalized odds, prices, and stats
  • Cross‑venue comparisons
• Only integrate native venue APIs if you need trading or user‑specific data

Best for:

• Dashboards comparing Polymarket vs Kalshi odds
• Forecasting tools, risk and hedging analytics
• Media sites embedding prediction‑market probabilities

3. Hybrid: cross‑venue frontend with Polymarket execution

• Use Codex for:
  • Discovery, odds, stats, charts
  • Cross‑venue normalization
• Use Polymarket native APIs for:
  • Account integration
  • Orders and fills
  • Venue‑specific resolution nuances (when needed)

Best for:

• Consumer apps where users read multi‑venue odds but execute on Polymarket

This hybrid pattern lets you ship quickly with Codex while still respecting venue‑native semantics for trading flows.

If you want to stop building and maintaining prediction‑market ETL and focus on your product instead, Codex’s prediction‑market API gives you trading‑grade, cross‑venue data and analytics with one integration.