Skip to main content

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.

In this recipe we’ll show you how to discover top prediction market traders, display detailed trader profiles with performance stats, show their market positions and P&L, and chart their trading activity over time.

Prediction market traders have rich on-chain performance data: win rate, P&L, volume, position sizing, and per-market breakdowns. This recipe covers 5 queries that work together: discover traders → view profile → see positions → chart performance → trade history.

​
Step 1: Trader Leaderboard

Build a sortable trader leaderboard with performance metrics across configurable time windows using filterPredictionTraders.

Ranking attributes are available at multiple windows: 12h, 24h, 1w, 1m, and “All” (all-time).Volume filters (e.g., totalVolumeUsdAll: { gte: 10000 }) are essential for meaningful leaderboards. Filter out low-activity traders.P&L per volume (pnlPerVolumeAll) normalizes profit by capital deployed, making it better for comparing traders of different sizes.Search matches against alias, primary address, or venue trader ID.

​
Step 2: Trader Profile & Detailed Stats

Fetch comprehensive stats for a single trader, broken down by time window, using detailedPredictionTraderStats.
Grab the trader ID from the previous queries to use here. We’ve used a sample trader ID for this example. Feel free to change it.
  • The trader object has the all-time aggregate profile: total volume, profit, biggest win/loss, trade count, active markets
  • Windowed stats (statsHour1 through statsDay30) give recent performance breakdowns
  • statsCurrency has all the monetary metrics, statsNonCurrency has counts, statsChange has period-over-period changes
  • heldTokenAcquisitionCostUsd / soldTokenAcquisitionCostUsd show the cost basis of currently held and already-sold positions
  • realizedProfitPercentage is the return on capital for the window
  • Use the windowed stats to build a time-period toggle (1h, 4h, 12h, 24h, 1w, 30d) on the trader profile

​
Step 3: Trader’s Market Positions

Show which markets a trader is active in, their positions, and per-market P&L with filterPredictionTraderMarkets.
Grab the trader ID, market ID, or event ID from the previous queries to use here. Or use the corresponding filterPredictionMarkets, filterPredictionEvents, or filterPredictionTraders queries to find relevant IDs.
Per-outcome position data: Each result has outcome0 and outcome1 with shares held, avg entry price, cost basis, realized P&L.hasOpenPosition: Filter to show only active positions vs historical ones.pnlStatus: Indicates the P&L state for the outcome (e.g., PROFIT, LOSS).avgEntryPriceCT: The average price the trader paid. Compare with current market price to estimate unrealized P&L.Cross-referencing: Use marketIds to find top traders for a market, or eventIds for an event. This powers “Top Traders” tabs on market/event pages.
You can also use predictionTraderMarketsStats as a simpler alternative for fetching a trader’s per-market stats without the filtering/ranking system:
Grab the trader ID from the previous queries to use here. We’ve used a sample trader ID for this example. Feel free to change it.

​
Step 4: Trader Performance Charts

Chart a trader’s performance over time (volume, P&L, trade activity, and cumulative profit) using predictionTraderBars.
Grab the trader ID from the previous queries to use here. We’ve used a sample trader ID for this example. Feel free to change it.
Chart types from this data:Cumulative P&L (line chart, the hero chart):
  • Plot cumulativeRealizedPnlCT over time. This is the signature trader performance chart
  • Shows the running total of realized profit/loss
  • Color the line green when positive, red when negative
Period P&L (bar chart):
  • realizedPnlUsd per bar. Green bars for profit, red for loss
  • Pair with the cumulative line above for a combo chart
Volume (bar chart):
  • volumeUsd or split into buyVolumeUsd / sellVolumeUsd
Win/Loss (stacked bar):
  • wins and losses per bar. Stacked or grouped bars showing resolution outcomes
Activity (line):
  • trades, buys, sells: trade frequency
  • uniqueMarkets: how diversified the trader is per period
Resolutions available: HOUR1, HOUR4, DAY1, WEEK1

​
Step 5: Trader’s Trade History

Show the individual trade-by-trade history for a trader with predictionTrades.
Grab the trader ID from the previous queries to use here. We’ve used a sample trader ID for this example. Feel free to change it.
  • Returns individual trades with full context: market, outcome, price, size, direction
  • tradeType indicates BUY or SELL
  • outcomeLabel shows which outcome was traded (e.g., “Yes” or “No”)
  • priceCollateral is the price paid per share
  • amount is the number of shares, amountUsd is the USD value
  • cursor enables pagination for loading more trades
  • Include predictionMarket to show market context alongside each trade

​
Putting It All Together

Here’s the recommended data flow: For a trader profile page, on page load (parallel queries):
  1. detailedPredictionTraderStats: profile header, summary stats, windowed performance
  2. filterPredictionTraderMarkets(traderIds, hasOpenPosition: true): active positions table
  3. predictionTraderBars: cumulative P&L chart
On tab switch:
  1. filterPredictionTraderMarkets(traderIds): all positions (when user switches to “All Positions” tab)
  2. predictionTrades(traderId): trade history (when user switches to “Trades” tab)
For a leaderboard page:
  1. filterPredictionTraders: the main ranked list with configurable sort
  2. Click a trader → navigate to their profile using the data flow above
Trader IDs: Format is typically protocol:address (e.g., Polymarket:0x1234...).CT vs USD: Collateral token (CT) values are preferred for prediction market P&L since the collateral is usually a stablecoin.Unrealized P&L: The API provides realized P&L. To estimate unrealized, compare avgEntryPriceCT from positions with current market price from filterPredictionMarkets.Win rate context: Always show win rate alongside trade count. A 100% win rate on 2 trades is less meaningful than 60% on 500 trades.Position sizing: totalCostBasisUsd shows how much capital a trader has deployed in a market, providing useful context alongside P&L.Cross-query use: filterPredictionTraderMarkets works bidirectionally. Filter by traderIds for a trader’s portfolio, or by marketIds/eventIds to find top traders for a market/event.
Check out the related endpoints in their respective API reference pages: