Polymarket API & Gamma Data: What Builders Get and How to Use It in Apps

Overview: How Polymarket API and Codex Fit Together

The Polymarket API and Gamma endpoints give builders everything they need to power native Polymarket trading flows—market discovery, odds, liquidity, and user positions. But they stop at the Polymarket ecosystem. Codex’s prediction market API sits alongside Polymarket as a dedicated onchain data layer, unifying Polymarket and Kalshi data, normalizing stats, and exposing trader analytics through one high-performance API designed for trading-grade apps.

If you’re building a frontend, analytics dashboard, or multi-platform prediction product, the practical pattern is:

• Use Polymarket Gamma + CLOB + Data API for direct trading and Polymarket-native UX.
• Add Codex when you need cross-platform coverage, windowed analytics, chart-ready series, and an infra-grade layer that you don’t have to maintain yourself.

This guide breaks down what each Polymarket API surface actually exposes, how rate limits affect frontend design, and when Codex becomes the right complement.

Polymarket API Stack: The Big Picture

Polymarket’s API is intentionally split by job-to-be-done, so you rarely hit just one endpoint family.

At a high level, you get:

• Gamma API – Market and event discovery, rich metadata.
• CLOB (orderbook) API – Live prices, order books, and trading endpoints.
• Data API v2 – Positions, trades, activity feed, historical prices.
• Relayer – Wallet transaction submission.
• WebSockets – Live public market updates and authenticated user streams.

Polymarket’s docs recommend:

• SDK-first when you can, to handle signing/retries/transport.
• Direct REST/WebSocket when your runtime isn’t supported or you need exact control.

For product and engineering teams, this means your architecture should treat each API segment as a separate layer in your app—discovery, pricing, user data, and trading.

Polymarket Gamma API: Markets, Events, and Discovery

What the Polymarket Gamma endpoints expose

The Polymarket Gamma API is your main discovery layer. It’s more than a simple market list.

Key Gamma endpoints include:

• /markets (Polymarket markets API)

  • Market metadata: title, description, status.
  • Liquidity, volume, open interest fields.
  • Probability-like prices (but not full order books).
  • Categories, tags, start/end dates.

• /events

  • Event containers grouping related markets.
  • Status flags, scheduling, categories.
  • High-level stats like total volume or participation.

• Comments, tags, public profiles

  • comments, tags, and public-profile fields support browse/search UX.
  • Useful for “event intelligence” pages, not just raw trading.

This makes Gamma ideal for:

• Market browse pages (home, category, trending).
• Search results (e.g., “US election”, “sports”, “crypto regulation”).
• Event-centric UX (grouped markets with shared narratives).

But Gamma alone is not enough for a production trading UI. You still need CLOB data for true odds, spreads, and book depth.

Using Gamma data in your frontend

Common integration patterns:

• Landing page & category views

  • Use /events + /markets for lists filtered by liquidity, volume, or category.
  • Show summary odds and a liquidity badge from Gamma’s fields.

• Market detail pre-load

  • Fetch the market via Gamma first for metadata (title, tags, dates).
  • Then hydrate odds and book from CLOB /price and /book.

• SEO & content surfaces

  • Comments, tags, and profiles can power content-driven discovery.
  • Good for “featured analysts”, “top traders”, and curated lists.

Gamma rate limits and UX implications

Polymarket’s API rate limits are endpoint-specific. For Gamma:

• General Gamma: 4000 requests / 10 seconds.
• /markets: 300 requests / 10 seconds.
• /events: 500 requests / 10 seconds.
• /comments: 200 requests / 10 seconds.
• /tags: 200 requests / 10 seconds.

Limits are enforced by Cloudflare, are IP-based, and use sliding windows.

For frontend teams, this implies:

• Do not hit /markets per market; page your list and batch requests.
• Cache common responses (e.g., top markets) in your backend.
• Design search/browse to be server-side rather than calling Gamma directly from clients.

Polymarket Odds and Liquidity: CLOB and Market Data

Polymarket odds API and orderbook data

For live odds, you should treat Gamma as a hint and rely on the CLOB market data API.

Core endpoints:

• /price / /prices – Point-in-time prices.

  • Each share is priced between $0.00 and $1.00, behaving like probabilities.
  • Displayed price typically comes from the bid/ask spread.

• /book – Polymarket orderbook API.

  • Full order book: bids, asks, resting orders.
  • Market details: min order size, tick size.
  • Flags like “neg-risk” and last trade price.

• /prices-history (CLOB layer)

  • Series of prices optimized for charting odds over time.

Polymarket’s docs emphasize: tighter spreads indicate more liquid markets. You should always pair odds with liquidity signals in your UI.

Liquidity and historical price series

Polymarket’s historical price series is tuned for frontend charts:

• Oldest-first series.
• Supports start, end, interval, or as_of.
• interval=max can cover the full lifetime of the market.
• Explicit start/end windows are capped at 15 days.
• Oldest markets go back to 2022, with 12-hour buckets by default.

In a frontend, this translates to:

• Short-range charts: use a specific start/end within 15 days.
• Long-range charts: use interval=max or coarser intervals.
• Display liquidity as depth and spread alongside any odds chart.

CLOB rate limits and trading behavior

CLOB endpoints have higher throughput:

• General CLOB: 9000 requests / 10 seconds.
• /book: 1500 requests / 10 seconds.
• /price: 1500 requests / 10 seconds.
• /prices-history: 1000 requests / 10 seconds.

Additionally:

• Per-signer order/cancel requests have separate token-bucket rate limits.
• A per-signer limiter entered warning mode on July 24, 2026, marking requests with Poly-RateLimit-Warning: true that would later be rejected.

For trading UIs and bots:

• Don’t hammer /book for each tick—use WebSockets for live updates.
• Implement client-side throttling for market switch and chart zoom.
• Monitor Poly-RateLimit-Warning to avoid degraded user experience.

Polymarket Data API v2: Positions, Activity, and Analytics

What the Data API v2 exposes

The Polymarket Data API v2 is your user-flow and analytics layer.

Key capabilities:

• Positions (/positions)

  • User holdings per market/outcome.
  • Useful for portfolio views and PnL calculations.

• Trades (/trades)

  • Trade history with cursor-pagination.
  • Basis for trade logs, receipts, and analytics.

• Activity (/activity)

  • Lifecycle events: splits, merges, redeems, not just trades.
  • Essential for wallets and dashboards that show “what happened” over time.

• Prices history (/prices-history v2)

  • Historical odds series aligned with Data API conventions.

Cursor-based pagination and reliability

Data API v2 is cursor-only, not offset-based:

• next_cursor must be passed through until it becomes null.
• has_more is exact; no guessing.
• Documented misses often return data: null or an empty list instead of errors.

This design matters for engineering:

• Treat the Data API as a stream, not a page index.
• Avoid assumptions about total counts; iterate until has_more is false.
• Resilience: be ready to handle empty data gracefully.

Data API v2 rate limits

Data API v2 limits:

• General: 800 requests / 10 seconds.
• /trades: 300 requests / 10 seconds.
• /positions: 200 requests / 10 seconds.
• /activity: 200 requests / 10 seconds.
• /prices-history: 200 requests / 10 seconds.

For analytics and reporting backends:

• Batch reads by user or market, not per-trade.
• Schedule heavier jobs off-peak and cache results.
• Consider a separate data warehouse fed by periodic pulls.

Public vs Authenticated Data: Architecting Your App

Polymarket draws a clear line between public reads and authenticated user activity.

• Public market data is available without credentials.

  • Gamma discovery.
  • CLOB market data (book, price, price history) for odds and liquidity.

• Authenticated flows cover user trades, orders, and wallet actions.

  • User WebSocket streams.
  • Relayer submission of signed transactions.
  • Account-specific endpoints where applicable.

Architecturally, this implies:

• Use public endpoints to render public screens (home, markets, charts).
• Avoid overusing authenticated endpoints for generic views; it hurts performance and scalability.
• Separate your public market data cache from user-specific services.

Polymarket’s docs also warn that onchain data can drift from third-party schemas when contracts change. They recommend verifying indexed contracts against the current contracts page—exactly the kind of maintenance overhead a dedicated data layer like Codex is built to handle for you.

Where Codex Comes In: A Dedicated On-Chain Prediction Market Data Layer

Codex prediction market API: scope and capabilities

Codex positions itself as the normalization and aggregation layer when Polymarket-only data isn’t enough.

Its prediction market API (currently beta and available on Growth/Enterprise tiers) covers:

• Polymarket and Kalshi through one unified GraphQL-style schema.
• Filterable events and markets (filterPredictionEvents, filterPredictionMarkets).
• Windowed statistics and all-time metrics for events, markets, and traders.
• Live order books and top-of-book prices.
• Trader analytics: leaderboards, trader-market histories, rankings.

Codex is explicit that prediction-market support is evolving and may be unreliable in some areas today, but the direction is clear: one API for cross-platform prediction market data, tuned for trading apps.

Why add Codex on top of Polymarket?

Reasons engineers and product teams layer Codex over Polymarket:

• Cross-platform coverage

  • You want Polymarket + Kalshi in one UX, with consistent fields and semantics.

• Enriched and normalized data

  • Codex turns raw smart contract events into structured objects (markets, trades, aggregates), saving months of ETL work.

• Windowed analytics out-of-the-box

  • Instead of custom pipelines, Codex exposes ready-to-use metrics: volume, liquidity, unique traders, odds changes across specific windows.

• Performance and scale

  • Codex documents rate limits of:
    • "Almost free" tier: 5 requests per second.
    • Growth: 300 requests per second.
    • Enterprise: custom, higher limits.
  • Many endpoints support batching (e.g., getTokenPrices with up to 25 inputs per request).

• Unified token + prediction market data

  • If your app is token-aware (wallets, DeFi dashboards), Codex’s broader onchain data: 80+ networks, 700M+ wallets, 70M+ tokens.

For teams who value reliability and correctness over hacky free solutions, Codex acts as the industrial-grade layer underneath your product, while Polymarket remains the execution venue.

Integration Patterns: Polymarket + Codex in Real Apps

Pattern 1: Native Polymarket frontend with Codex analytics

Use case: You’re building a Polymarket-focused app but want robust analytics without building your own indexers.

• Discovery & trading

  • Use Gamma + CLOB + Data API for all Polymarket-specific flows.
  • WebSockets for real-time odds and user trades.

• Analytics & dashboards

  • Use Codex prediction market API to compute windowed market stats, trader leaderboards, and cross-event aggregates.
  • Codex becomes your primary analytics backend; you avoid custom ETL.

Pattern 2: Multi-platform prediction app

Use case: You aggregate markets from Polymarket, Kalshi, and potentially more platforms.

• Market listing

  • Hit Codex filterPredictionMarkets to get cross-platform markets with unified fields.
  • Use Polymarket Gamma only when you need detailed native metadata.

• Odds & liquidity

  • For day-to-day odds charts and price comparisons, Codex’s windowed stats and orderbook summaries suffice.
  • Fall back to Polymarket CLOB endpoints for venue-specific details or bespoke order book views.

• Trader analytics

  • Codex’s trader endpoints give market history and rankings across platforms.

Pattern 3: Token-aware trading dashboard with prediction markets

Use case: You already use Codex for token prices and onchain data; prediction markets are a new feature.

• Token layer

  • Continue to use Codex for token prices, chart data, holders, balances, and scam filtering.

• Prediction layer

  • Enable Codex prediction market endpoints to:
    • Pull markets and events.
    • Show odds alongside token prices.
    • Provide unified PnL across tokens and prediction positions.

Codex’s query-then-subscribe pattern is useful here:

• Use queries for initial page loads and historical charts.
• Use subscriptions for live dashboards where odds update in real time.
• Be aware that very high-frequency feeds can make subscriptions more expensive than polling; choose per usage.

When to Invest in a Dedicated On-Chain Data Layer

You don’t always need a dedicated data layer. But for certain product profiles, it’s hard to avoid.

You should consider Codex or similar infra when:

• You operate at Series A+ scale and serve millions of users.
• You support multiple chains, launchpads, and prediction venues.
• Latency and correctness are non-negotiable for trading, portfolio, or analytics.
• You want to consolidate vendors and reduce your failure surface.

Maintaining custom indexers, RPC nodes, and ETL pipelines across 80+ networks and several prediction platforms can consume entire teams. Codex’s core value proposition is simple:

"We index the chain so you don’t have to."

For prediction markets, that means:

• No need to track schema drift when contracts change.
• No need to rebuild odds and liquidity metrics when new markets launch.
• A single, mature pipeline that evolves as the ecosystem changes.

Practical Tips for Frontend and Analytics Teams

To make Polymarket API and Codex work smoothly together:

• Separate concerns

  • Polymarket: trading UX and venue-native data.
  • Codex: cross-platform analytics, token + prediction coverage.

• Respect rate limits

  • Batch and cache Gamma and Data API calls.
  • Use WebSockets for live CLOB data instead of aggressive polling.
  • Plan backend workers around endpoint-specific quotas.

• Normalize your data model

  • Define a shared internal model for markets, events, and orders.
  • Map Polymarket fields and Codex fields into that model consistently.

• Build a caching strategy

  • Use a shared cache for public market data.
  • Periodically refresh historical series and aggregates.

• Benchmark latency and throughput

  • Test Codex’s Growth/Enterprise limits (up to 300 rps and beyond) against your traffic profile.
  • Measure how much time you save vs. building in-house indexers.