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

Top all-time profitable traders

Test this query in the Explorer →

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
    }
  }
}

Best win rate this week (minimum volume filter)

Test this query in the Explorer →

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
    }
  }
}

Highest 24h PnL

Test this query in the Explorer →

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
    }
  }
}

Search for a trader

Test this query in the Explorer →

query SearchTrader {
  filterPredictionTraders(phrase: "HorizonSplendidView", limit: 10) {
    count
    results {
      id
      trader {
        alias
        primaryAddress
        profileImageUrl
        labels
      }
      totalVolumeUsdAll
      totalProfitCTAll
      winRate24h
    }
  }
}

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.

Full trader profile with windowed stats

Test this query in the Explorer →

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

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.

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.

Open positions sorted by P&L

Test this query in the Explorer →

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
      }
    }
  }
}

Top traders for a specific market

Test this query in the Explorer →

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
      }
    }
  }
}

Top traders in a specific event

Test this query in the Explorer →

query EventTopTraders {
  filterPredictionTraderMarkets(
    eventIds: ["yourEventId"]
    rankings: [{ attribute: totalVolumeUsd, direction: DESC }]
    limit: 25
  ) {
    count
    results {
      id
      traderId
      marketId
      market {
        id
        label
        eventLabel
      }
      totalRealizedPnlUsd
      totalVolumeUsd
      hasOpenPosition
    }
  }
}

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.

Simple position list with predictionTraderMarketsStats

Test this query in the Explorer →

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.

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.

Trader performance bars

Test this query in the Explorer →

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.

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.

Trader trade history

Test this query in the Explorer →

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

detailedPredictionTraderStats: profile header, summary stats, windowed performance
filterPredictionTraderMarkets(traderIds, hasOpenPosition: true): active positions table
predictionTraderBars: cumulative P&L chart

On tab switch:

filterPredictionTraderMarkets(traderIds): all positions (when user switches to “All Positions” tab)
predictionTrades(traderId): trade history (when user switches to “Trades” tab)

For a leaderboard page:

filterPredictionTraders: the main ranked list with configurable sort
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:

First steps

Codex for Agents

Concepts

Recipes

Migration Guides

Resources

Prediction Traders

Step 1: Trader Leaderboard

Step 2: Trader Profile & Detailed Stats

Step 3: Trader’s Market Positions

Step 4: Trader Performance Charts

Step 5: Trader’s Trade History

Putting It All Together

​Step 1: Trader Leaderboard

​Step 2: Trader Profile & Detailed Stats

​Step 3: Trader’s Market Positions

​Step 4: Trader Performance Charts

​Step 5: Trader’s Trade History

​Putting It All Together

Step 1: Trader Leaderboard

Step 2: Trader Profile & Detailed Stats

Step 3: Trader’s Market Positions

Step 4: Trader Performance Charts

Step 5: Trader’s Trade History

Putting It All Together