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

# Prediction Event Dashboard

> Learn how to build a comprehensive prediction event detail page with markets, charts, trades, and real-time pricing

In this recipe we'll walk through building a prediction event detail page, the kind of page Polymarket and Kalshi center their UX around. An event like "2024 Presidential Election" contains multiple related markets ("Who wins?", "Popular vote margin?", "Which states flip?").

We'll combine multiple Codex endpoints to populate every section: event metadata, market probabilities, multi-market charts, aggregated activity, trade history, and market drill-downs.

## Step 1: Event Metadata & Market List

<Info>
  For the examples below to work, you'll need an ID of an event. You can get that by using [filterPredictionEvents](/api-reference/queries/filterpredictionevents). Take the ouput of that and replace the `eventId` value in the queries below.

  Unforunately, Prediction Markets are ever changing so it's hard for us to hardcode an example like we can with tokens.
</Info>

Start by fetching the event details and all its markets in a single call with [`detailedPredictionEventStats`](/api-reference/queries/detailedpredictioneventstats). This returns event metadata, the full list of markets, aggregated stats across time windows, and lifecycle information.

<AccordionGroup>
  <Accordion title="Full event metadata with markets and stats">
    [Test this query in the Explorer →](/explore)

    ```graphql theme={null} theme={null}
    query DetailedPredictionEventStats {
      detailedPredictionEventStats(input: { eventId: "yourEventId" }) {
        eventId
        lastTransactionAt
        predictionEvent {
          id
          protocol
          venueEventId
          status
          question
          url
          rulesPrimary
          rulesSecondary
          tags
          opensAt
          closesAt
          resolvesAt
          resolvedAt
          resolution {
            result
            source
          }
          imageLargeUrl
          imageThumbUrl
          createdAt
          updatedAt
          networkId
          marketIds
          categories {
            name
            slug
            subcategories {
              name
              slug
            }
          }
        }
        predictionMarkets {
          id
          protocol
          venueMarketId
          eventId
          question
          label
          eventLabel
          outcomeLabels
          outcomeIds
          resolution {
            result
            source
          }
          imageThumbUrl
          createdAt
          opensAt
          closesAt
          resolvesAt
          resolvedAt
          networkId
        }
        statsDay1 {
          start
          end
          statsCurrency {
            volumeUsd
            volumeCT
            openLiquidityUsd
            closeLiquidityUsd
            openOpenInterestUsd
            closeOpenInterestUsd
          }
          statsNonCurrency {
            trades
            uniqueTraders
          }
          statsChange {
            volumeChange
            openLiquidityChange
            openOpenInterestChange
            tradesChange
            uniqueTradersChange
          }
          scores {
            trending
            relevance
          }
        }
        allTimeStats {
          volumeUsd
          volumeCT
          venueVolumeUsd
          venueVolumeCT
        }
        lifecycle {
          ageSeconds
          expectedLifespanSeconds
          timeToResolutionSeconds
          isResolved
        }
      }
    }
    ```
  </Accordion>
</AccordionGroup>

<Info>
  This is the core call that populates the event header, market list sidebar, and summary stats. It gives you everything you need to render the top of the page in one request. Stats are available at multiple windows. `statsDay1` is shown above, but `statsHour1`, `statsHour4`, `statsHour12`, `statsWeek1` follow the same structure.
</Info>

## Step 2: Market Outcome Pricing

To show current probabilities (best ask price) for each market's outcomes (the core of any prediction market UI), use [`filterPredictionMarkets`](/api-reference/queries/filterpredictionmarkets) scoped to the event. This returns real-time bid/ask pricing, spread, liquidity depth, and volume for each outcome.

<AccordionGroup>
  <Accordion title="Current outcome pricing for all markets in an event">
    [Test this query in the Explorer →](/explore)

    ```graphql theme={null} theme={null}
    query EventMarketPricing {
      filterPredictionMarkets(
        eventIds: ["yourEventId"]
        rankings: [
          { outcome: outcome0, outcomeAttribute: bestAskCT, direction: DESC }
        ]
      ) {
        count
        results {
          id
          status
          market {
            id
            label
            question
            imageThumbUrl
          }
          outcome0 {
            label
            bestAskCT
            bestBidCT
            spreadCT
            lastPriceCT
            liquidityCT
            volumeUsd24h
            priceChange24h
          }
          outcome1 {
            label
            bestAskCT
            bestBidCT
            spreadCT
            lastPriceCT
            liquidityCT
            volumeUsd24h
            priceChange24h
          }
          volumeUsdAll
          liquidityUsd
          openInterestUsd
        }
      }
    }
    ```
  </Accordion>
</AccordionGroup>

* The `bestAskCT` price (in collateral token, e.g., USDC) represents the current implied probability (0.65 = 65% chance)
* Ranking by outcome0's `bestAskCT` in DESC order puts the highest-probability outcomes at the top
* You can also rank by market-level attributes like `volumeUsd24h` or `trendingScore24h`
* The spread (`bestAskCT - bestBidCT`) indicates market efficiency
* This is the data that powers the market list showing "Yes 65¢ / No 35¢" for each market

## Step 3: Multi-Market Probability Chart

The signature visualization: a multi-line chart showing how probabilities for the top markets in an event have moved over time. Use [`predictionEventTopMarketsBars`](/api-reference/queries/predictioneventtopmarketsbars).

<AccordionGroup>
  <Accordion title="Top 5 markets by weekly volume">
    [Test this query in the Explorer →](/explore)

    ```graphql theme={null} theme={null}
    query EventTopMarketsBars {
      predictionEventTopMarketsBars(
        input: {
          eventId: "yourEventId"
          from: 1773100000
          to: 1773700000
          resolution: hour1
          limit: 5
          rankBy: "volumeUsd1w"
          rankDirection: "DESC"
        }
      ) {
        eventId
        predictionEvent {
          id
          question
        }
        marketBars {
          marketId
          predictionMarket {
            id
            label
            outcomeLabels
          }
          bars {
            t
            outcome0 {
              priceCollateralToken {
                o
                h
                l
                c
              }
              volumeUsd
              trades
            }
            outcome1 {
              priceCollateralToken {
                o
                h
                l
                c
              }
            }
            openInterestUsd {
              o
              h
              l
              c
            }
          }
        }
      }
    }
    ```
  </Accordion>
</AccordionGroup>

* Returns OHLC bars for the top N markets (up to 10) in a single request
* `rankBy` determines which markets are "top". Use `volumeUsd1w` for most active, or rank by outcome attribute with `rankByOutcome` + `rankByOutcomeAttribute`
* Plot `outcome0.priceCollateralToken.c` (close price) for each market as a line to get the multi-candidate probability chart
* You can also pass explicit `marketIds` instead of using ranking to choose which markets to chart

## Step 4: Event-Level Aggregated Charts

For charts showing aggregated activity across the entire event (total volume, liquidity, open interest over time), use [`predictionEventBars`](/api-reference/queries/predictioneventbars).

<AccordionGroup>
  <Accordion title="Event volume, liquidity, and open interest over time">
    [Test this query in the Explorer →](/explore)

    ```graphql theme={null} theme={null}
    query EventBars {
      predictionEventBars(
        input: {
          eventId: "yourEventId"
          from: 1773100000
          to: 1773700000
          resolution: hour1
        }
      ) {
        eventId
        bars {
          t
          volumeUsd
          buyVolumeUsd
          sellVolumeUsd
          totalVolumeUsd
          trades
          uniqueTraders
          liquidityUsd {
            o
            h
            l
            c
          }
          openInterestUsd {
            o
            h
            l
            c
          }
        }
      }
    }
    ```
  </Accordion>
</AccordionGroup>

* This aggregates data across ALL markets in the event
* Use for volume bar charts, liquidity area charts, and open interest line charts
* `buyVolumeUsd` / `sellVolumeUsd` breakdown enables buy/sell pressure analysis
* `uniqueTraders` shows participation growth over time

## Step 5: Trade Feed

Show recent trades across all markets in the event with [`predictionTrades`](/api-reference/queries/predictiontrades).

<AccordionGroup>
  <Accordion title="Recent trades for an event">
    [Test this query in the Explorer →](/explore)

    ```graphql theme={null} theme={null}
    query EventTrades {
      predictionTrades(input: { eventId: "yourEventId", limit: 50 }) {
        items {
          marketId
          outcomeId
          protocol
          tradeType
          maker
          traderId
          timestamp
          outcomeIndex
          outcomeLabel
          priceUsd
          priceCollateral
          amount
          amountUsd
          transactionHash
          networkId
        }
        cursor
      }
    }
    ```
  </Accordion>
</AccordionGroup>

* Returns trades across all markets in the event, sorted by most recent
* Each trade includes the `outcomeLabel` and `outcomeIndex` so you can show "Bought Yes @ \$0.65"
* `cursor` enables pagination for loading more trades
* `traderId` can be used to link to trader profiles
* Can also query by `marketId` for single-market trade feeds

## Step 6: Single Market Drill-Down

When a user clicks on a specific market within the event, fetch detailed chart data and token holder information.

<AccordionGroup>
  <Accordion title="Single market OHLC chart with bid/ask">
    [Test this query in the Explorer →](/explore)

    ```graphql theme={null} theme={null}
    query MarketDrillDown {
      predictionMarketBars(
        input: {
          marketId: "yourMarketId"
          from: 1773100000
          to: 1773700000
          resolution: hour1
        }
      ) {
        marketId
        bars {
          t
          volumeUsd
          trades
          uniqueTraders
          openInterestUsd {
            o
            h
            l
            c
          }
          outcome0 {
            priceCollateralToken {
              o
              h
              l
              c
            }
            liquidityCollateralToken {
              o
              h
              l
              c
            }
            bidCollateralToken {
              o
              h
              l
              c
            }
            askCollateralToken {
              o
              h
              l
              c
            }
            volumeUsd
            trades
            buys
            sells
          }
          outcome1 {
            priceCollateralToken {
              o
              h
              l
              c
            }
            liquidityCollateralToken {
              o
              h
              l
              c
            }
            bidCollateralToken {
              o
              h
              l
              c
            }
            askCollateralToken {
              o
              h
              l
              c
            }
            volumeUsd
            trades
            buys
            sells
          }
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Outcome token holders">
    [Test this query in the Explorer →](/explore)

    ```graphql theme={null} theme={null}
    query TokenHolders {
      predictionTokenHolders(
        input: { marketId: "yourMarketId", tokenId: "yourTokenId", limit: 25 }
      ) {
        items {
          walletAddress
          amount
          predictionTrader {
            alias
          }
        }
        total
        cursor
      }
    }
    ```
  </Accordion>
</AccordionGroup>

<Info>
  **Getting the `tokenId`:** The `tokenId` is extracted from the `outcomeIds` array on the market object (returned in Step 1). Each `outcomeId` is a compound string like `46553455570564517989191023458705371521436514261892866503067981558938998232024:Polymarket:0xc5d563a36ae78145c45a50134d48a1215220f80a:137`. The `tokenId` is just the first segment before the first colon (e.g., `46553455570564517989191023458705371521436514261892866503067981558938998232024`).

  For a binary market, `outcomeIds[0]` is the "Yes" token and `outcomeIds[1]` is the "No" token. Query once per outcome to get holders for each side.
</Info>

* Market bars give per-outcome OHLC data for price, liquidity, bid, and ask, enabling candlestick charts and bid/ask spread visualization
* Token holders shows who holds the most of each outcome token, with their trader alias if available
* Token holder data is only available for Polymarket (on-chain ERC-1155 tokens on Polygon). Kalshi does not expose holder data.

## Putting It All Together

Here's the recommended data flow for an event dashboard:

**On page load (parallel queries):**

1. `detailedPredictionEventStats`: event metadata, market list, aggregated stats
2. `filterPredictionMarkets(eventIds)`: current outcome pricing for all markets
3. `predictionEventTopMarketsBars`: multi-market probability chart data
4. `predictionEventBars`: event-level volume/liquidity charts

**After initial load:**

5. `predictionTrades(eventId)`: trade feed

**On user interaction (drill-down):**

6. `predictionMarketBars`: when user clicks a specific market
7. `predictionTokenHolders`: when user views holders tab

<Note>
  To alert on a market without polling — volume spikes, price moves, or trade-count bursts over rolling windows — set up a prediction market metrics webhook. See [Webhooks](/concepts/webhooks#prediction_market_metrics_event) for setup.
</Note>

<Tip>
  **Optimizing calls:** Queries 1-4 are independent and can be run in parallel to minimize page load time.

  **Probabilities:** The `bestAskCT` or `priceCollateralToken.c` values represent implied probability when the collateral token is a stablecoin. A price of 0.65 means the market implies a 65% chance.

  **Multi-outcome events:** Each market is binary (two outcomes), but an event can have many markets. For a "Who wins the election?" event, each candidate gets their own market.

  **CT vs USD:** Collateral token values are more precise for prediction markets since they avoid exchange rate fluctuations.

  **Sorting the market list:** Rank by `outcome0.bestAskCT DESC` to show the highest-probability outcome first, or by `volumeUsd24h DESC` for most active.

  **Status values:** Events and markets can be `OPEN`, `SUSPENDED`, or `RESOLVED`.
</Tip>

Check out the related endpoints in their respective API reference pages:

* [detailedPredictionEventStats](/api-reference/queries/detailedpredictioneventstats)
* [filterPredictionMarkets](/api-reference/queries/filterpredictionmarkets)
* [predictionEventTopMarketsBars](/api-reference/queries/predictioneventtopmarketsbars)
* [predictionEventBars](/api-reference/queries/predictioneventbars)
* [predictionTrades](/api-reference/queries/predictiontrades)
* [predictionMarketBars](/api-reference/queries/predictionmarketbars)
* [predictionTokenHolders](/api-reference/queries/predictiontokenholders)