> ## Documentation Index
> Fetch the complete documentation index at: https://docs.codex.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Polymarket API

> Access real-time Polymarket prediction market data through the Codex API. Track market prices, outcome probabilities, trading volumes, events, and trader analytics.

Polymarket is the world's largest decentralized prediction market platform, built on Polygon. Codex indexes all Polymarket markets, events, trades, and trader activity, providing comprehensive access to market data, outcome prices, trading volumes, and real-time event streams through a unified GraphQL API.

<Info>
  **Prediction Market data is currently in beta**. It is actively being worked on and improved, but may be unreliable.

  At least for the time being, these endpoints require a Growth or Enterprise plan. [Learn more](https://dashboard.codex.io/dashboard/billing?utm_source=codex\&utm_medium=docs\&utm_campaign=billing).
</Info>

## Platform Information

| Property        | Value        |
| --------------- | ------------ |
| Platform        | Polymarket   |
| Network         | Polygon      |
| Chain ID        | `137`        |
| Protocol Filter | `POLYMARKET` |
| Status          | Live         |

## Why Use Codex Over the Polymarket API Directly?

|                         | Codex API                                                                                                                                                                            | Polymarket API                                                                                                                                                                                 |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Rate Limits**         | 1,000+ req/s                                                                                                                                                                         | \~30 req/s                                                                                                                                                                                     |
| **Ranking signals**     | Sort events or markets by trending score, volume, liquidity, open interest, trades, unique traders, or `% change` of any of these at 5m / 1h / 4h / 12h / 24h / 1w                   | Gamma `/events` `order` parameter only accepts `volume_24hr`, `volume`, `liquidity`, `start_date`, `end_date`, `competitive`, `closed_time`. No sub-day windows, no momentum or trending score |
| **Time-windowed stats** | Volume, trades, unique traders, liquidity, open interest, and `% change` for each at 5m / 1h / 4h / 12h / 24h / 1w                                                                   | Volume only, at 24h / 1wk / 1mo / 1yr. No trade counts, no unique-trader counts, no time-windowed liquidity or OI change                                                                       |
| **Filtering**           | Filter events and markets on every stat above (volume, OI, liquidity, trade count, unique traders, % changes, trending score, market count) plus categories, dates, status, protocol | `active`, `closed`, `archived`, `liquidity_min/max`, `volume_min/max`, `start_date_min/max`, `end_date_min/max`, `tag`                                                                         |
| **Cross-venue**         | One query, one schema, one ranking system covering Polymarket and Kalshi (plus future venues)                                                                                        | Polymarket only. Integrating Kalshi means a second vendor, second auth, second schema                                                                                                          |

## Understanding Events and Markets

**Events** are collections of related **markets**. For example:

* Event: "Champions League Final 2026"
  * Market 1: "Will Team A win?"
  * Market 2: "Will the score be over 2.5 goals?"
  * Market 3: "Will there be a penalty?"

Use [`filterPredictionEvents`](/api-reference/queries/filterpredictionevents) to find trending high-level topics. Use [`filterPredictionMarkets`](/api-reference/queries/filterpredictionmarkets) to find trending markets.

## ID Formats

Polymarket uses specific ID formats to uniquely identify markets, events, and traders across the platform:

### Market ID

Format: `<marketAddress>:Polymarket:<exchangeAddress>:<networkId>`

Example: `0x25aa90b3cd98305e849189b4e8b770fc77fe89bccb7cf9656468414e01145d38:Polymarket:0xc5d563a36ae78145c45a50134d48a1215220f80a:137`

* `marketAddress`: The unique contract address for this specific market outcome
* `Polymarket`: The protocol identifier
* `exchangeAddress`: The Polymarket exchange contract address (typically `0xc5d563a36ae78145c45a50134d48a1215220f80a`)
* `networkId`: The blockchain network ID (`137` for Polygon)

### Event ID

Format: `<eventSlug>:Polymarket:<exchangeAddress>:<networkId>`

Example: `67284:Polymarket:0xc5d563a36ae78145c45a50134d48a1215220f80a:137`

* `eventSlug`: The Polymarket event identifier (venue ID)
* `Polymarket`: The protocol identifier
* `exchangeAddress`: The Polymarket exchange contract address
* `networkId`: The blockchain network ID (`137` for Polygon)

### Trader ID

Format: `<address>:Polymarket`

Example: `0x742d35cc6634c0532925a3b844bc9e7595f0beb6:Polymarket`

* `address`: The trader's wallet address
* `Polymarket`: The protocol identifier

## Supported APIs

### Market & Event API

* [Filter Prediction Events](/api-reference/queries/filterpredictionevents) — Query Polymarket events with advanced filtering
* [Filter Prediction Markets](/api-reference/queries/filterpredictionmarkets) — Search and filter Polymarket markets by volume, liquidity, category, and other criteria
* [Get Detailed Event Stats](/api-reference/queries/detailedpredictioneventstats) — Fetch detailed statistics for Polymarket events
* [Get Detailed Market Stats](/api-reference/queries/detailedpredictionmarketstats) — Retrieve comprehensive trading metrics for any Polymarket market
* [Get Event Price Bars](/api-reference/queries/predictioneventbars) — Retrieve event-level price history for charting
* [Get Market Price Bars](/api-reference/queries/predictionmarketbars) — Fetch OHLC price data for Polymarket markets

### Trading & Activity API

* [Get Prediction Trades](/api-reference/queries/predictiontrades) — Query trade history and trading activity on Polymarket
* [Get Trader Stats](/api-reference/queries/detailedpredictiontraderstats) — Retrieve comprehensive trader performance metrics
* [Filter Traders](/api-reference/queries/filterpredictiontraders) — Discover top Polymarket traders by volume, PnL, win rate, and other metrics
* [Get Trader Market Stats](/api-reference/queries/predictiontradermarketsstats) — Analyze trader performance across specific markets
* [Get Trader Bars](/api-reference/queries/predictiontraderbars) — Track trader activity over time with time-series data
* [Filter Trader Markets](/api-reference/queries/filterpredictiontradermarkets) — Query markets a specific trader has participated in

### Market Discovery API

* [Get Prediction Categories](/api-reference/queries/predictioncategories) — Browse Polymarket categories (Politics, Crypto, Sports, etc.)
* [Get Token Holders](/api-reference/queries/predictiontokenholders) — Query outcome token holders and current positions

## Example Queries

### Find Trending Polymarket Events

```graphql theme={null}
{
  filterPredictionEvents(
    filters: {
      protocol: POLYMARKET
      status: OPEN
    }
    rankings: [{ attribute: trendingScore24h, direction: DESC }]
    limit: 10
  ) {
    count
    results {
      event {
        question
        description
      }
      marketCount
      volumeUsd24h
      trendingScore24h
    }
  }
}
```

### Find Top Polymarket Markets by 24h Volume

```graphql theme={null}
{
  filterPredictionMarkets(
    filters: {
      protocol: POLYMARKET
      status: OPEN
    }
    rankings: [{ attribute: volumeUsd24h, direction: DESC }]
    limit: 10
  ) {
    count
    results {
      id
      eventLabel
      protocol
      market {
        question
        label
        status
        protocol
        networkId
      }
      volumeUsd24h
      liquidityUsd
      trades24h
      uniqueTraders24h
      outcome0 {
        label
        lastPriceUsd
      }
      outcome1 {
        label
        lastPriceUsd
      }
    }
  }
}
```

### Find Polymarket Markets in Politics Category

```graphql theme={null}
{
  filterPredictionMarkets(
    filters: {
      protocol: POLYMARKET
      status: OPEN
      categories: ["politics"]
    }
    rankings: [{ attribute: volumeUsd24h, direction: DESC }]
    limit: 20
  ) {
    count
    results {
      id
      eventLabel
      market {
        question
      }
      categories
      volumeUsd24h
      liquidityUsd
      outcome0 {
        label
        lastPriceUsd
      }
      outcome1 {
        label
        lastPriceUsd
      }
    }
  }
}
```

### Find Top Polymarket Traders

```graphql theme={null}
{
  filterPredictionTraders(
    filters: { protocol: POLYMARKET }
    rankings: [{ attribute: TOTAL_VOLUME_USD_ALL, direction: DESC }]
    limit: 50
  ) {
    count
    results {
      trader {
        primaryAddress
        alias
      }
      totalVolumeUsdAll
      totalProfitUsdAll
      totalTradesAll
      activeMarketsCount
      winRate24h
      realizedPnlUsd24h
    }
  }
}
```

### Get Price History for a Market

```graphql theme={null}
{
  predictionMarketBars(
    input: {
      marketId: "0x25aa90b3cd98305e849189b4e8b770fc77fe89bccb7cf9656468414e01145d38:Polymarket:0xc5d563a36ae78145c45a50134d48a1215220f80a:137"
      resolution: hour1
      from: 1772665600
      to: 1773270400
    }
  ) {
    marketId
    bars {
      t
      volumeUsd
      trades
      uniqueTraders
      outcome0 {
        priceUsd {
          o
          h
          l
          c
        }
      }
      outcome1 {
        priceUsd {
          o
          h
          l
          c
        }
      }
    }
  }
}
```

## Try It in the Explorer

Test any Polymarket query directly in the [Codex GraphQL Explorer](/explore).

## Recipes

Step-by-step guides for building with Polymarket data:

<CardGroup cols={2}>
  <Card title="Discover Prediction Markets" icon="magnifying-glass" href="/recipes/predictions/discover-markets">
    Browse categories, trending events, and filter markets.
  </Card>

  <Card title="Prediction Traders" icon="users" href="/recipes/predictions/traders">
    Trader leaderboards, profiles, and performance analytics.
  </Card>

  <Card title="Prediction Charts" icon="chart-line" href="/recipes/predictions/charts">
    Outcome probability charts, multi-market comparisons, and OHLC data.
  </Card>

  <Card title="Prediction Event Dashboard" icon="table-columns" href="/recipes/predictions/event-dashboard">
    Build a complete event detail page with real-time data.
  </Card>
</CardGroup>

## Related Resources

* [Supported Prediction Markets Overview](/prediction-markets) — All supported platforms
* [Supported Networks Overview](/networks) — All supported blockchain networks