Skip to main content
In this recipe, we’ll show you how to use filterPredictionEvents and 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 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).
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.
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 to build sortable, filterable event lists.
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. This is useful for showing specific binary questions across events, or building market-level leaderboards.
Use event IDs from the events query above (e.g., event.id).
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 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.
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: