> ## 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.

# Predictions Overview

> How prediction events, markets, outcomes, and traders fit together in the Codex API, and which GraphQL query to reach for in each case.

The prediction endpoints are organized around four things: **events**, **markets**, **traders**, and the **trades** that connect them. Knowing which one you're asking about tells you which query you want.

<Info>
  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>

## The data model

An **event** is a real-world topic. It holds one or more **markets**, each a single yes/no or multi-way question. Every market resolves through its **outcomes**, and each outcome has a price that reads as an implied probability. **Traders** take positions in those outcomes, and every position change is a **trade**.

```
Event            "2026 World Cup"
└─ Market        "Will Brazil win?"
   ├─ Outcome    "Yes"  ($0.34 → 34% implied)
   └─ Outcome    "No"   ($0.66 → 66% implied)
      └─ Trades  who bought or sold, when, and at what price
```

The practical consequence: event-level data aggregates across every market underneath it. If you want the headline number for "2026 World Cup" you query the event. If you want the odds on a specific team, you query the market.

## Pick your endpoint

Each group in the sidebar maps to one layer of that model.

<div className="nowrap-code-table">
  ### Events

  | The data you need | Find it with this |
  | - | - |
  | Discover events by topic, protocol, status, or trending score | [`filterPredictionEvents`](/api-reference/queries/filterpredictionevents) |
  | Volume, liquidity, and trader counts for one event, windowed and all-time | [`detailedPredictionEventStats`](/api-reference/queries/detailedpredictioneventstats) |
  | Event-level price history for charting | [`predictionEventBars`](/api-reference/queries/predictioneventbars) |
  | One chart series per leading market inside an event, for a comparison view | [`predictionEventTopMarketsBars`](/api-reference/queries/predictioneventtopmarketsbars) |
  | The category and subcategory vocabulary used to browse and filter events | [`predictionCategories`](/api-reference/queries/predictioncategories) |

  ### Markets

  | The data you need | Find it with this |
  | - | - |
  | Discover markets across every event by volume, liquidity, or ranking | [`filterPredictionMarkets`](/api-reference/queries/filterpredictionmarkets) |
  | Markets within a single event, with entrant, segment, and ladder metadata already parsed | [`eventScopedFilterPredictionMarkets`](/api-reference/queries/eventscopedfilterpredictionmarkets) |
  | Full records for markets you already have IDs for | [`predictionMarkets`](/api-reference/queries/predictionmarkets) |
  | Windowed and all-time stats for one market | [`detailedPredictionMarketStats`](/api-reference/queries/detailedpredictionmarketstats) |
  | OHLC price history for a market | [`predictionMarketBars`](/api-reference/queries/predictionmarketbars) |
  | Latest price, or price at a specific timestamp | [`predictionMarketPrice`](/api-reference/queries/predictionmarketprice) |
  | Who holds the outcome tokens for a market, and how much | [`predictionTokenHolders`](/api-reference/queries/predictiontokenholders) |
</div>

<Tip>
  Reach for `eventScopedFilterPredictionMarkets` instead of `filterPredictionMarkets` when you're rendering a single event page. It returns structured classification metadata (country codes, period and stat grouping, parsed numeric and date rungs) so you don't have to parse market labels client-side.
</Tip>

<div className="nowrap-code-table">
  ### Traders

  | The data you need | Find it with this |
  | - | - |
  | Leaderboards: rank traders by volume, realized PnL, trade count, or biggest win | [`filterPredictionTraders`](/api-reference/queries/filterpredictiontraders) |
  | Full records for traders you already have IDs for | [`predictionTraders`](/api-reference/queries/predictiontraders) |
  | Aggregate performance for one trader | [`detailedPredictionTraderStats`](/api-reference/queries/detailedpredictiontraderstats) |
  | How one trader has performed market by market | [`predictionTraderMarketsStats`](/api-reference/queries/predictiontradermarketsstats) |
  | Trader-market records filtered across traders, markets, and events at once | [`filterPredictionTraderMarkets`](/api-reference/queries/filterpredictiontradermarkets) |
  | Everything a trader currently holds | [`predictionTraderHoldings`](/api-reference/queries/predictiontraderholdings) |
  | A trader's performance over time, for charting | [`predictionTraderBars`](/api-reference/queries/predictiontraderbars) |

  ### Trades and order books

  | The data you need | Find it with this |
  | - | - |
  | Trade history, filterable by market, event, or trader, with cursor pagination | [`predictionTrades`](/api-reference/queries/predictiontrades) |
  | Live bids and asks for a set of outcomes, pulled from the venue's CLOB | [`predictionOutcomeOrderBooks`](/api-reference/queries/predictionoutcomeorderbooks) |
</div>

## Staying live

Five subscriptions mirror the queries above for real-time updates: [`onPredictionTradesCreated`](/api-reference/subscriptions/onpredictiontradescreated), [`onDetailedPredictionMarketStatsUpdated`](/api-reference/subscriptions/ondetailedpredictionmarketstatsupdated), [`onDetailedPredictionEventStatsUpdated`](/api-reference/subscriptions/ondetailedpredictioneventstatsupdated), [`onPredictionMarketBarsUpdated`](/api-reference/subscriptions/onpredictionmarketbarsupdated), and [`onPredictionEventBarsUpdated`](/api-reference/subscriptions/onpredictioneventbarsupdated).

## Venue coverage

| Platform | Protocol filter | Status |
| - | - | - |
| [Polymarket](/prediction-markets/polymarket) | `POLYMARKET` | Live |
| [Kalshi](/prediction-markets/kalshi) | `KALSHI` | Live |

Coverage is not identical across venues. Kalshi runs as a CFTC-regulated exchange and does not expose individual trader identity, so trader data is unavailable for Kalshi entirely: the Traders queries above cannot be used with it, `traderId` filtering is unavailable, and Kalshi trades carry no maker and no buy/sell direction (every trade returns as `TRADE`). Event, market, and trade data work the same on both venues. `predictionOutcomeOrderBooks` covers Polymarket and Kalshi, and returns `null` for outcomes from anywhere else.

See [Supported Prediction Markets](/prediction-markets/index) for the full platform breakdown.

## Recipes

<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 Event Dashboard" icon="table-columns" href="/recipes/predictions/event-dashboard">
    Build a complete event detail page with real-time data.
  </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 Traders" icon="users" href="/recipes/predictions/traders">
    Trader leaderboards, profiles, and performance analytics.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.