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

# Discover Prediction Markets

> Build prediction market discovery pages with filterPredictionEvents and filterPredictionMarkets: filter, rank, and search events and markets.

In this recipe, we'll show you how to use [`filterPredictionEvents`](https://docs.codex.io/api-reference/queries/filterpredictionevents) and [`filterPredictionMarkets`](https://docs.codex.io/api-reference/queries/filterpredictionmarkets) to build discovery pages for prediction markets: filterable, sortable lists that let users browse what's trending, search by topic, and find markets that match specific criteria.

There are two levels of discovery: **events** (containers that group related markets, like "2024 Presidential Election") and **markets** (individual binary questions, like "Will candidate X win?"). A third query, `filterPredictionTraders`, powers trader leaderboards and is covered in the [Prediction Traders](https://docs.codex.io/recipes/predictions/traders.md) recipe.

## Step 1: Browse the Category Taxonomy

Before building filters, fetch the full category tree so you can populate category dropdowns and sidebar navigation. Categories are nested up to 5 levels deep (e.g., Sports > Football > NFL).

> [accordion] Fetch all prediction categories
>
> [Test this query in the Explorer →](https://docs.codex.io/explore.md)
>
> ```graphql theme={null} theme={null}
> query PredictionCategories {
>   predictionCategories {
>     name
>     slug
>     subcategories {
>       name
>       slug
>       subcategories {
>         name
>         slug
>       }
>     }
>   }
> }
> ```

> [!TIP]
>
> This is a lightweight call. Fetch once and cache client-side. Use the `slug` values when filtering events or markets by passing them in the `categories` filter.

## Step 2: Discover Trending Events

Events are the primary discovery unit. They group related markets together (e.g., "2024 Presidential Election" contains markets for each candidate, state, etc.). Use [`filterPredictionEvents`](https://docs.codex.io/api-reference/queries/filterpredictionevents) to build sortable, filterable event lists.

> [accordion] Trending events on Polymarket
>
> [Test this query in the Explorer →](https://docs.codex.io/explore.md)
>
> ```graphql theme={null} theme={null}
> query TrendingEvents {
>   filterPredictionEvents(
>     filters: { protocol: [POLYMARKET], status: [OPEN] }
>     rankings: [{ attribute: trendingScore24h, direction: DESC }]
>     limit: 20
>   ) {
>     count
>     page
>     results {
>       id
>       event {
>         id
>         protocol
>         status
>         slug
>         question
>         description
>         imageThumbUrl
>         venueUrl
>         closesAt
>         resolvesAt
>       }
>       status
>       markets {
>         id
>         label
>       }
>       marketCount
>       categories
>       trendingScore24h
>       relevanceScore24h
>       liquidityUsd
>       openInterestUsd
>       volumeUsd24h
>       volumeChange24h
>       trades24h
>       uniqueTraders24h
>     }
>   }
> }
> ```

> [accordion] High-volume sports events
>
> [Test this query in the Explorer →](https://docs.codex.io/explore.md)
>
> ```graphql theme={null} theme={null}
> query SportsEvents {
>   filterPredictionEvents(
>     filters: { protocol: [POLYMARKET], status: [OPEN], categories: ["sports"] }
>     rankings: [{ attribute: volumeUsd24h, direction: DESC }]
>     limit: 20
>   ) {
>     count
>     results {
>       id
>       event {
>         question
>         imageThumbUrl
>         closesAt
>       }
>       marketCount
>       categories
>       volumeUsd24h
>       volumeChange24h
>       trades24h
>       liquidityUsd
>       openInterestUsd
>       trendingScore24h
>     }
>   }
> }
> ```

> [accordion] Search events by keyword
>
> [Test this query in the Explorer →](https://docs.codex.io/explore.md)
>
> ```graphql theme={null} theme={null}
> query SearchEvents {
>   filterPredictionEvents(
>     phrase: "election"
>     filters: { status: [OPEN] }
>     rankings: [{ attribute: relevanceScore24h, direction: DESC }]
>     limit: 20
>   ) {
>     count
>     results {
>       id
>       event {
>         question
>         description
>         imageThumbUrl
>       }
>       marketCount
>       relevanceScore24h
>       volumeUsd24h
>       liquidityUsd
>     }
>   }
> }
> ```

> [!NOTE]
>
> **Scoring explained (events):**
>
> * `trendingScore24h` combines volume, trades, and momentum, making it best for "what's hot right now"
> * `relevanceScore24h` factors in liquidity and market maturity, making it best for "most important"
> * `competitiveScore24h` is only available on **markets** (via `filterPredictionMarkets`), not events, since competitiveness measures how close a market's outcomes are to each other.
>
> All score, volume, and trade metrics are available at 5m, 1h, 4h, 12h, 24h, and 1w windows. Use `relatedEventIds` to build "Related Events" sections.

## Step 3: Discover Individual Markets

For more granular discovery, filter at the individual market level with [`filterPredictionMarkets`](https://docs.codex.io/api-reference/queries/filterpredictionmarkets). This is useful for showing specific binary questions across events, or building market-level leaderboards.

> [accordion] Most competitive open markets (closest to 50/50)
>
> [Test this query in the Explorer →](https://docs.codex.io/explore.md)
>
> ```graphql theme={null} theme={null}
> query CompetitiveMarkets {
>   filterPredictionMarkets(
>     filters: { status: [OPEN] }
>     rankings: [{ attribute: competitiveScore24h, direction: DESC }]
>     limit: 20
>   ) {
>     count
>     results {
>       id
>       eventLabel
>       market {
>         id
>         eventId
>         protocol
>         label
>         question
>         imageThumbUrl
>         status
>         closesAt
>       }
>       status
>       outcome0 {
>         label
>         bestAskCT
>         bestBidCT
>         spreadCT
>         lastPriceCT
>         liquidityCT
>         volumeUsd24h
>         priceChange24h
>       }
>       outcome1 {
>         label
>         bestAskCT
>         bestBidCT
>         spreadCT
>         lastPriceCT
>         liquidityCT
>         volumeUsd24h
>         priceChange24h
>       }
>       competitiveScore24h
>       trendingScore24h
>       liquidityUsd
>       openInterestUsd
>       volumeUsd24h
>       trades24h
>       priceCompetitiveness
>     }
>   }
> }
> ```

> [accordion] Markets within a specific event, ranked by probability
>
> Use event IDs from the events query above (e.g., `event.id`).
>
> [Test this query in the Explorer →](https://docs.codex.io/explore.md)
>
> ```graphql theme={null} theme={null}
> query EventMarkets {
>   filterPredictionMarkets(
>     eventIds: ["yourEventId"]
>     rankings: [
>       { outcome: outcome0, outcomeAttribute: bestAskCT, direction: DESC }
>     ]
>     limit: 50
>   ) {
>     count
>     results {
>       id
>       market {
>         id
>         label
>         question
>       }
>       outcome0 {
>         label
>         bestAskCT
>         bestBidCT
>         lastPriceCT
>         volumeUsd24h
>       }
>       outcome1 {
>         label
>         bestAskCT
>         bestBidCT
>         lastPriceCT
>         volumeUsd24h
>       }
>       volumeUsdAll
>       liquidityUsd
>       openInterestUsd
>     }
>   }
> }
> ```

> [accordion] High open-interest markets closing soon
>
> [Test this query in the Explorer →](https://docs.codex.io/explore.md)
>
> ```graphql theme={null} theme={null}
> query ClosingSoon {
>   filterPredictionMarkets(
>     filters: { status: [OPEN], closesAt: { lte: 1773700000 } }
>     rankings: [{ attribute: openInterestUsd, direction: DESC }]
>     limit: 20
>   ) {
>     count
>     results {
>       id
>       market {
>         id
>         label
>         question
>         closesAt
>         resolvesAt
>       }
>       outcome0 {
>         label
>         bestAskCT
>         lastPriceCT
>       }
>       outcome1 {
>         label
>         bestAskCT
>         lastPriceCT
>       }
>       openInterestUsd
>       liquidityUsd
>       volumeUsd24h
>     }
>   }
> }
> ```

> [!NOTE]
>
> **Market-level vs outcome-level ranking:** Use `attribute` for market-wide metrics (volume, trending score) or `outcome` + `outcomeAttribute` for outcome-specific metrics (best ask price, liquidity per outcome).
>
> * `bestAskCT` is the implied probability when collateral is a stablecoin (0.65 = 65% chance)
> * `spreadCT` = `bestAskCT - bestBidCT`. Tighter spreads indicate more efficient markets
> * `priceCompetitiveness` measures how close outcome prices are to each other
> * `volumeImbalance24h` shows buy/sell pressure asymmetry

## Step 4: Building Filter UIs

Combine the above into a practical filter interface:

**Category navigation:** Use `predictionCategories` to build sidebar/tabs, pass selected `slug` into `filters.categories`

**Status tabs:** OPEN | RESOLVED | all. Map to `filters.status` using [`PredictionEventStatus`](https://docs.codex.io/api-reference/enums/predictioneventstatus) values

**Sort dropdown: map user-friendly labels to ranking attributes:**

* "Trending" → `trendingScore24h` DESC
* "Most Volume" → `volumeUsd24h` DESC
* "Most Liquidity" → `liquidityUsd` DESC
* "Newest" → `age` ASC
* "Closing Soon" → `closesAt` ASC (with status OPEN filter)
* "Most Competitive" → `competitiveScore24h` DESC (markets only, via `filterPredictionMarkets`)

**Time window selector:** All metrics are available at 5m, 1h, 4h, 12h, 24h, 1w. Let users toggle the time window for scores and volume displays.

**Pagination:** Use `offset` and `limit` for page-based navigation. `count` in the response gives the total matching results.

## Step 5: Combining Events and Markets

The recommended pattern for a discovery page that shows events with their top markets inline:

1. Fetch events with `filterPredictionEvents` (gives you `marketCount` and basic market IDs)
2. For each displayed event, fetch market pricing with `filterPredictionMarkets(eventIds: [eventId])` ranked by `outcome0.bestAskCT` DESC
3. Display as: Event card → list of markets with Yes/No prices

This two-query approach avoids over-fetching while giving complete pricing data.

> [!TIP]
>
> **Protocol filter:** Use `protocol: [POLYMARKET]` or `protocol: [KALSHI]` to scope to a specific venue.
>
> **Scores are pre-computed:** Trending, relevance, and competitive scores are calculated server-side, so there's no need to compute them yourself.
>
> **Events vs markets:** Start with events for the main discovery page, use markets for drill-down or when you need outcome-level data.
>
> **Performance:** `filterPredictionEvents` and `filterPredictionMarkets` are optimized for fast reads from a search index, making them safe to call on every filter change.

Check out related endpoints in their respective API reference pages:

* [filterPredictionEvents](https://docs.codex.io/api-reference/queries/filterpredictionevents.md)
* [filterPredictionMarkets](https://docs.codex.io/api-reference/queries/filterpredictionmarkets.md)
* [predictionCategories](https://docs.codex.io/api-reference/queries/predictioncategories.md)
* [filterPredictionTraders](https://docs.codex.io/api-reference/queries/filterpredictiontraders.md)


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