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

> Learn how to build trader leaderboards, profiles, and portfolio analytics for prediction market traders

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`](https://docs.codex.io/api-reference/queries/filterpredictiontraders).

> [accordion] Top all-time profitable traders
>
> [Test this query in the Explorer →](https://docs.codex.io/explore.md)
>
> ```graphql theme={null} theme={null}
> query TopTraders {
>   filterPredictionTraders(
>     rankings: [{ attribute: TOTAL_PROFIT_CT_ALL, direction: DESC }]
>     limit: 25
>   ) {
>     count
>     page
>     results {
>       id
>       trader {
>         id
>         venueTraderId
>         protocol
>         alias
>         primaryAddress
>         profileImageUrl
>         profileUrl
>         labels
>       }
>       totalVolumeUsdAll
>       totalProfitUsdAll
>       totalProfitCTAll
>       totalTradesAll
>       activeMarketsCount
>       pnlPerVolumeAll
>       biggestWinUsd
>       biggestLossUsd
>       firstTradeTimestamp
>       lastTradeTimestamp
>       volumeUsd24h
>       realizedPnlUsd24h
>       realizedProfitPercentage24h
>       trades24h
>       winRate24h
>       heldTokenAcquisitionCostUsd
>     }
>   }
> }
> ```

> [accordion] Best win rate this week (minimum volume filter)
>
> [Test this query in the Explorer →](https://docs.codex.io/explore.md)
>
> ```graphql theme={null} theme={null}
> query BestWinRate {
>   filterPredictionTraders(
>     filters: { totalVolumeUsdAll: { gte: 10000 } }
>     rankings: [{ attribute: WIN_RATE_1W, direction: DESC }]
>     limit: 25
>   ) {
>     count
>     results {
>       id
>       trader {
>         alias
>         primaryAddress
>         profileImageUrl
>       }
>       totalVolumeUsdAll
>       totalProfitCTAll
>       winRate24h
>       trades24h
>       realizedPnlUsd24h
>     }
>   }
> }
> ```

> [accordion] Highest 24h PnL
>
> [Test this query in the Explorer →](https://docs.codex.io/explore.md)
>
> ```graphql theme={null} theme={null}
> query HighestPnL {
>   filterPredictionTraders(
>     rankings: [{ attribute: REALIZED_PNL_USD_24H, direction: DESC }]
>     limit: 25
>   ) {
>     count
>     results {
>       id
>       trader {
>         alias
>         primaryAddress
>         profileImageUrl
>       }
>       realizedPnlUsd24h
>       realizedPnlCT24h
>       realizedProfitPercentage24h
>       volumeUsd24h
>       trades24h
>       winRate24h
>     }
>   }
> }
> ```

> [accordion] Search for a trader
>
> [Test this query in the Explorer →](https://docs.codex.io/explore.md)
>
> ```graphql theme={null} theme={null}
> query SearchTrader {
>   filterPredictionTraders(phrase: "HorizonSplendidView", limit: 10) {
>     count
>     results {
>       id
>       trader {
>         alias
>         primaryAddress
>         profileImageUrl
>         labels
>       }
>       totalVolumeUsdAll
>       totalProfitCTAll
>       winRate24h
>     }
>   }
> }
> ```

> [!NOTE]
>
> **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`](https://docs.codex.io/api-reference/queries/detailedpredictiontraderstats).

> [!NOTE]
>
> 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.

> [accordion] Full trader profile with windowed stats
>
> [Test this query in the Explorer →](https://docs.codex.io/explore.md)
>
> ```graphql theme={null} theme={null}
> query TraderProfile {
>   detailedPredictionTraderStats(
>     input: { traderId: "0x02227b8f5a9636e895607edd3185ed6ee5598ff7:Polymarket" }
>   ) {
>     traderId
>     lastTransactionAt
>     trader {
>       id
>       protocol
>       venueTraderId
>       alias
>       primaryAddress
>       linkedAddresses
>       profileImageUrl
>       profileUrl
>       labels
>       totalVolumeUsd
>       totalVolumeCT
>       allTimeProfitUsd
>       allTimeProfitCT
>       biggestWinUsd
>       biggestWinCT
>       biggestLossUsd
>       biggestLossCT
>       totalTradesCount
>       activeMarketsCount
>       firstTradeTimestamp
>       lastTradeTimestamp
>     }
>     allTimeStats {
>       totalVolumeUsd
>       totalVolumeCT
>       totalProfitUsd
>       totalProfitCT
>     }
>     statsDay1 {
>       start
>       end
>       lastTransactionAt
>       statsCurrency {
>         volumeUsd
>         volumeCT
>         buyVolumeUsd
>         sellVolumeUsd
>         realizedPnlUsd
>         realizedPnlCT
>         averageSwapAmountUsd
>         averageProfitUsdPerTrade
>         realizedProfitPercentage
>         heldTokenAcquisitionCostUsd
>         soldTokenAcquisitionCostUsd
>       }
>       statsNonCurrency {
>         trades
>         buys
>         sells
>         wins
>         losses
>         uniqueMarkets
>       }
>       statsChange {
>         volumeChange
>         realizedPnlChange
>         tradesChange
>         winsChange
>         lossesChange
>         uniqueMarketsChange
>       }
>     }
>   }
> }
> ```

* 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

> [!NOTE]
>
> Each toggle interval maps to one exact field name:
>
> | Time window | Field name |
> | - | - |
> | 1 hour | `statsHour1` |
> | 4 hours | `statsHour4` |
> | 12 hours | `statsHour12` |
> | 24 hours | `statsDay1` |
> | 1 week | `statsWeek1` |
> | 30 days | `statsDay30` |
> | All-time | `allTimeStats` |
>
> Note the one-week window is `statsWeek1`, not `statsDay7`.
>
> Note the 30-day window is `statsDay30`, not `statsMonth1`.
>
> These six windowed fields plus `allTimeStats` are the complete set. There is no `statsDay7`, `statsDay3`, `statsDay14`, or `statsMonth1`.

## Step 3: Trader's Market Positions

Show which markets a trader is active in, their positions, and per-market P\&L with [`filterPredictionTraderMarkets`](https://docs.codex.io/api-reference/queries/filterpredictiontradermarkets).

> [!NOTE]
>
> Grab the trader ID, market ID, or event ID from the previous queries to use here. Or use the corresponding [`filterPredictionMarkets`](https://docs.codex.io/api-reference/queries/filterpredictionmarkets), [`filterPredictionEvents`](https://docs.codex.io/api-reference/queries/filterpredictionevents), or [`filterPredictionTraders`](https://docs.codex.io/api-reference/queries/filterpredictiontraders) queries to find relevant IDs.

> [accordion] Open positions sorted by P\&L
>
> [Test this query in the Explorer →](https://docs.codex.io/explore.md)
>
> ```graphql theme={null} theme={null}
> query OpenPositions {
>   filterPredictionTraderMarkets(
>     traderIds: ["0x02227b8f5a9636e895607edd3185ed6ee5598ff7:Polymarket"]
>     filters: { hasOpenPosition: true }
>     rankings: [{ attribute: totalVolumeUsd, direction: DESC }]
>     limit: 25
>   ) {
>     count
>     results {
>       id
>       traderId
>       marketId
>       eventId
>       market {
>         id
>         eventId
>         label
>         question
>         eventLabel
>         imageThumbUrl
>         outcome0Label
>         outcome1Label
>       }
>       hasOpenPosition
>       totalRealizedPnlUsd
>       totalRealizedPnlCT
>       totalVolumeUsd
>       totalTrades
>       totalCostBasisUsd
>       totalSharesHeld
>       pnlPerVolumeMarket
>       outcome0 {
>         outcomeId
>         isWinningOutcome
>         sharesHeld
>         avgEntryPriceUsd
>         avgEntryPriceCT
>         costBasisUsd
>         buys
>         sells
>         buyVolumeUsd
>         sellVolumeUsd
>         realizedPnlUsd
>         pnlStatus
>       }
>       outcome1 {
>         outcomeId
>         isWinningOutcome
>         sharesHeld
>         avgEntryPriceCT
>         costBasisUsd
>         buys
>         sells
>         realizedPnlUsd
>         pnlStatus
>       }
>     }
>   }
> }
> ```

> [accordion] Top traders for a specific market
>
> [Test this query in the Explorer →](https://docs.codex.io/explore.md)
>
> ```graphql theme={null} theme={null}
> query MarketTopTraders {
>   filterPredictionTraderMarkets(
>     marketIds: ["yourMarketId"]
>     rankings: [{ attribute: totalVolumeUsd, direction: DESC }]
>     limit: 25
>   ) {
>     count
>     results {
>       id
>       traderId
>       marketId
>       market {
>         id
>         label
>         question
>         eventLabel
>       }
>       totalRealizedPnlUsd
>       totalVolumeUsd
>       totalTrades
>       hasOpenPosition
>       outcome0 {
>         sharesHeld
>         avgEntryPriceCT
>         realizedPnlUsd
>         pnlStatus
>       }
>       outcome1 {
>         sharesHeld
>         avgEntryPriceCT
>         realizedPnlUsd
>         pnlStatus
>       }
>     }
>   }
> }
> ```

> [accordion] Top traders in a specific event
>
> [Test this query in the Explorer →](https://docs.codex.io/explore.md)
>
> ```graphql theme={null} theme={null}
> query EventTopTraders {
>   filterPredictionTraderMarkets(
>     eventIds: ["yourEventId"]
>     rankings: [{ attribute: totalVolumeUsd, direction: DESC }]
>     limit: 25
>   ) {
>     count
>     results {
>       id
>       traderId
>       marketId
>       market {
>         id
>         label
>         eventLabel
>       }
>       totalRealizedPnlUsd
>       totalVolumeUsd
>       hasOpenPosition
>     }
>   }
> }
> ```

> [!NOTE]
>
> **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:

> [!NOTE]
>
> 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.

> [accordion] Simple position list with predictionTraderMarketsStats
>
> [Test this query in the Explorer →](https://docs.codex.io/explore.md)
>
> ```graphql theme={null} theme={null}
> query TraderPositions {
>   predictionTraderMarketsStats(
>     input: {
>       traderId: "0x02227b8f5a9636e895607edd3185ed6ee5598ff7:Polymarket"
>       limit: 25
>     }
>   ) {
>     items {
>       traderId
>       marketId
>       hasOpenPosition
>       predictionMarket {
>         id
>         label
>         question
>         eventLabel
>         outcomeLabels
>         winningOutcomeId
>         resolution {
>           result
>           source
>         }
>       }
>       outcome0Stats {
>         sharesHeld
>         avgEntryPriceCT
>         costBasisCT
>         realizedPnlCT
>         pnlStatus
>         buys
>         sells
>         buyVolumeCT
>         sellVolumeCT
>       }
>       outcome1Stats {
>         sharesHeld
>         avgEntryPriceCT
>         costBasisCT
>         realizedPnlCT
>         pnlStatus
>         buys
>         sells
>         buyVolumeCT
>         sellVolumeCT
>       }
>     }
>     cursor
>   }
> }
> ```

## Step 4: Trader Performance Charts

Chart a trader's performance over time (volume, P\&L, trade activity, and cumulative profit) using [`predictionTraderBars`](https://docs.codex.io/api-reference/queries/predictiontraderbars).

> [!NOTE]
>
> 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.

> [accordion] Trader performance bars
>
> [Test this query in the Explorer →](https://docs.codex.io/explore.md)
>
> ```graphql theme={null} theme={null}
> query TraderPerformance {
>   predictionTraderBars(
>     input: {
>       traderId: "0x02227b8f5a9636e895607edd3185ed6ee5598ff7:Polymarket"
>       from: 1773100000
>       to: 1773700000
>       resolution: day1
>     }
>   ) {
>     traderId
>     trader {
>       id
>       alias
>       primaryAddress
>       profileImageUrl
>     }
>     bars {
>       t
>       trades
>       buys
>       sells
>       uniqueMarkets
>       volumeUsd
>       volumeCT
>       buyVolumeUsd
>       sellVolumeUsd
>       wins
>       losses
>       realizedPnlUsd
>       realizedPnlCT
>       cumulativeRealizedPnlUsd
>       cumulativeRealizedPnlCT
>     }
>   }
> }
> ```

**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`](https://docs.codex.io/api-reference/queries/predictiontrades).

> [!NOTE]
>
> 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.

> [accordion] Trader trade history
>
> [Test this query in the Explorer →](https://docs.codex.io/explore.md)
>
> ```graphql theme={null} theme={null}
> query TraderTrades {
>   predictionTrades(
>     input: {
>       traderId: "0x02227b8f5a9636e895607edd3185ed6ee5598ff7:Polymarket"
>       limit: 50
>     }
>   ) {
>     items {
>       marketId
>       outcomeId
>       protocol
>       tradeType
>       maker
>       traderId
>       timestamp
>       outcomeIndex
>       outcomeLabel
>       priceUsd
>       priceCollateral
>       amount
>       amountCollateral
>       amountUsd
>       transactionHash
>       blockNumber
>       networkId
>       predictionMarket {
>         id
>         label
>         question
>         eventLabel
>         outcomeLabels
>       }
>     }
>     cursor
>   }
> }
> ```

* 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:**

4. `filterPredictionTraderMarkets(traderIds)`: all positions (when user switches to "All Positions" tab)
5. `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

> [!TIP]
>
> **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:

* [filterPredictionTraders](https://docs.codex.io/api-reference/queries/filterpredictiontraders.md)
* [detailedPredictionTraderStats](https://docs.codex.io/api-reference/queries/detailedpredictiontraderstats.md)
* [filterPredictionTraderMarkets](https://docs.codex.io/api-reference/queries/filterpredictiontradermarkets.md)
* [predictionTraderMarketsStats](https://docs.codex.io/api-reference/queries/predictiontradermarketsstats.md)
* [predictionTraderBars](https://docs.codex.io/api-reference/queries/predictiontraderbars.md)
* [predictionTrades](https://docs.codex.io/api-reference/queries/predictiontrades.md)


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