> ## 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. # filterPredictionTraderMarkets > Filters trader-market records using trader, market, event, and ranking criteria. filterPredictionTraderMarkets query reference: arguments and response fields. > [!NOTE] > > At least for the time being, this endpoint requires a Growth or Enterprise plan. [Learn more](https://dashboard.codex.io/dashboard/billing?utm_source=codex\&utm_medium=docs\&utm_campaign=billing). > [!NOTE] > > **Kalshi does not provide trader data**. These endpoints only work with Polymarket data. Kalshi's API does not expose individual trader information due to privacy considerations on their regulated exchange. ## GraphQL ``` type Query { # Requires a Growth or Enterprise plan. filterPredictionTraderMarkets( filters: PredictionTraderMarketFilters phrase: String traderIds: [String!] excludeTraderIds: [String!] marketIds: [String!] excludeMarketIds: [String!] eventIds: [String!] excludeEventIds: [String!] rankings: [PredictionTraderMarketRanking!] limit: Int offset: Int ): PredictionTraderMarketFilterConnection } enum PredictionProtocol { POLYMARKET KALSHI } type FilterTrader { id: String! venueTraderId: String! protocol: PredictionProtocol! alias: String primaryAddress: String linkedAddresses: [String!] profileImageUrl: String profileUrl: String labels: [String!] } enum PredictionEventStatus { OPEN SUSPENDED RESOLVED CANCELLED PENDING } type FilterTraderMarket { id: String! eventId: String! protocol: PredictionProtocol! venueMarketId: String! label: String question: String eventLabel: String imageThumbUrl: String outcome0Label: String outcome1Label: String status: PredictionEventStatus! closesAt: Int! resolvedAt: Int } type PredictionTrader { id: String! protocol: PredictionProtocol! venueTraderId: String! alias: String primaryAddress: String linkedAddresses: [String!] profileImageUrl: String profileUrl: String totalTradesCount: Int! totalVolumeUsd: String! totalVolumeCT: String! firstTradeTimestamp: Int! lastTradeTimestamp: Int! biggestWinUsd: String! biggestWinCT: String! biggestLossUsd: String! biggestLossCT: String! allTimeProfitUsd: String! allTimeProfitCT: String! activeMarketsCount: Int! labels: [String!] createdAt: Int! updatedAt: Int! } type PredictionResolution { result: String source: String } type PredictionSubSubcategory { name: String! slug: String! } type PredictionSubcategory { name: String! slug: String! subcategories: [PredictionSubSubcategory!] } type PredictionCategory { name: String! slug: String! subcategories: [PredictionSubcategory!] } enum PredictionMetadataType { SPORTS } type SportsTeam { abbreviation: String! altAbbreviations: [String!] name: String league: String logo: String alias: String color: String providerId: Int isHome: Boolean } enum SportsTimezone { UTC } type SportsMarketEnrichedMetadata { sportsMarketType: String league: String teams: [SportsTeam!] gameStartDate: String gameStartTime: String gameStartTimeSeconds: Int gameStartTimezone: SportsTimezone } type PredictionMarketEnrichedMetadata { metadataType: PredictionMetadataType! sports: SportsMarketEnrichedMetadata } type PredictionMarket { id: String! protocol: PredictionProtocol! venueMarketId: String! venueMarketSlug: String eventId: String venueEventId: String question: String label: String suggestedLabel: String eventLabel: String rules: String rules2: String venueOutcomeIds: [String!]! outcomeIds: [String!]! outcomeLabels: [String!] resolution: PredictionResolution imageLargeUrl: String imageThumbUrl: String imageSmallUrl: String createdAt: Int updatedAt: Int opensAt: Int closesAt: Int resolvesAt: Int resolvedAt: Int observedAt: Int! networkId: Int exchangeAddress: String categories: [PredictionCategory!] winningOutcomeId: String enrichedMetadata: PredictionMarketEnrichedMetadata } enum PredictionTraderMarketPnlStatus { WIN LOSS NEUTRAL } type PredictionTraderOutcomeFilterResult { outcomeId: String! isWinningOutcome: Boolean! sharesHeld: String! actualSharesHeld: String! avgEntryPriceUsd: String! avgEntryPriceCT: String! costBasisUsd: String! costBasisCT: String! buys: Int! sells: Int! buyVolumeUsd: String! sellVolumeUsd: String! buyVolumeCT: String! sellVolumeCT: String! buyVolumeShares: String! sellVolumeShares: String! realizedPnlUsd: String! realizedPnlCT: String! currentPriceUsd: String currentPriceCT: String currentPositionValueUsd: String currentPositionValueCT: String unrealizedPnlUsd: String unrealizedPnlCT: String pnlStatus: PredictionTraderMarketPnlStatus! firstTradeTimestamp: Int! lastTradeTimestamp: Int! } type PredictionTraderMarketFilterResult { id: String! timestamp: Int! traderId: String! marketId: String! eventId: String! trader: FilterTrader! market: FilterTraderMarket! predictionTrader: PredictionTrader predictionMarket: PredictionMarket hasOpenPosition: Boolean! winningOutcomeId: String totalRealizedPnlUsd: String! totalRealizedPnlCT: String! totalVolumeUsd: String! totalVolumeCT: String! totalVolumeShares: String! totalBuys: Int! totalSells: Int! totalTrades: Int! totalCostBasisUsd: String! totalCostBasisCT: String! totalSharesHeld: String! totalCurrentPositionValueUsd: String totalCurrentPositionValueCT: String totalUnrealizedPnlUsd: String totalUnrealizedPnlCT: String pnlPerVolumeMarket: String! profitPerTradeUsd: String! firstTradeTimestamp: Int! lastTradeTimestamp: Int! outcome0: PredictionTraderOutcomeFilterResult! outcome1: PredictionTraderOutcomeFilterResult! } type PredictionTraderMarketFilterConnection { count: Int! page: Int! results: [PredictionTraderMarketFilterResult!]! } input NumberFilter { gte: Float gt: Float lte: Float lt: Float } input PredictionTraderMarketFilters { protocol: [PredictionProtocol!] status: [PredictionEventStatus!] traderLabels: [String!] excludeTraderLabels: [String!] hasOpenPosition: Boolean outcome0PnlStatus: [PredictionTraderMarketPnlStatus!] outcome1PnlStatus: [PredictionTraderMarketPnlStatus!] timestamp: NumberFilter firstTradeTimestamp: NumberFilter lastTradeTimestamp: NumberFilter totalRealizedPnlUsd: NumberFilter totalRealizedPnlCT: NumberFilter totalVolumeUsd: NumberFilter totalVolumeCT: NumberFilter totalVolumeShares: NumberFilter totalBuys: NumberFilter totalSells: NumberFilter totalTrades: NumberFilter totalCostBasisUsd: NumberFilter totalCostBasisCT: NumberFilter totalSharesHeld: NumberFilter pnlPerVolumeMarket: NumberFilter profitPerTradeUsd: NumberFilter outcome0RealizedPnlUsd: NumberFilter outcome0Buys: NumberFilter outcome0Sells: NumberFilter outcome0SharesHeld: NumberFilter outcome0CostBasisUsd: NumberFilter outcome1RealizedPnlUsd: NumberFilter outcome1Buys: NumberFilter outcome1Sells: NumberFilter outcome1SharesHeld: NumberFilter outcome1CostBasisUsd: NumberFilter } enum PredictionTraderMarketRankingAttribute { timestamp firstTradeTimestamp lastTradeTimestamp totalRealizedPnlUsd totalRealizedPnlCT totalVolumeUsd totalVolumeCT totalVolumeShares totalBuys totalSells totalTrades totalCostBasisUsd totalCostBasisCT totalSharesHeld pnlPerVolumeMarket profitPerTradeUsd outcome0RealizedPnlUsd outcome0Buys outcome0Sells outcome0SharesHeld outcome0CostBasisUsd outcome1RealizedPnlUsd outcome1Buys outcome1Sells outcome1SharesHeld outcome1CostBasisUsd } enum RankingDirection { ASC DESC } input PredictionTraderMarketRanking { attribute: PredictionTraderMarketRankingAttribute! direction: RankingDirection } ``` ## Example: Top profitable trader positions [Test this query in the Explorer →](https://docs.codex.io/explore.md) ```graphql theme={null} { filterPredictionTraderMarkets( rankings: [ { attribute: totalRealizedPnlUsd, direction: DESC } ] filters: { status: RESOLVED } limit: 10 ) { count page results { id trader { alias primaryAddress profileImageUrl } market { question eventLabel status closesAt outcome0Label outcome1Label } totalRealizedPnlUsd totalVolumeUsd totalTrades totalBuys totalSells pnlPerVolumeMarket profitPerTradeUsd hasOpenPosition outcome0 { sharesHeld avgEntryPriceUsd realizedPnlUsd pnlStatus buys sells } outcome1 { sharesHeld avgEntryPriceUsd realizedPnlUsd pnlStatus buys sells } } } } ``` ```json Example Response (truncated) theme={null} { "data": { "filterPredictionTraderMarkets": { "count": 10, "page": 0, "results": [ { "id": "0x019782cab5d844f02bafb71f512758be78579f3c:Polymarket:0xc65e24cc10c071c4643186287441624cb41040a3c66a2971e5fc44479cc25146:Polymarket:0xc5d563a36ae78145c45a50134d48a1215220f80a:137", "trader": { "alias": "majorexploiter", "primaryAddress": null, "profileImageUrl": null }, "market": { "question": "Will Arsenal FC win on 2026-03-01?", "eventLabel": "Arsenal FC vs. Chelsea FC", "status": "RESOLVED", "closesAt": 1772382600, "outcome0Label": "Yes", "outcome1Label": "No" }, "totalRealizedPnlUsd": "2416340.457365", "totalVolumeUsd": "11481708.960435", "totalTrades": 659, "totalBuys": 658, "totalSells": 1, "pnlPerVolumeMarket": "0.2105", "profitPerTradeUsd": "3666.6774770333839150227617602427921092564492", "hasOpenPosition": false, "outcome0": { "sharesHeld": "0", "avgEntryPriceUsd": "0", "realizedPnlUsd": "2416340.457365", "pnlStatus": "WIN", "buys": 658, "sells": 1 }, "outcome1": { "sharesHeld": "0", "avgEntryPriceUsd": "0", "realizedPnlUsd": "0", "pnlStatus": "NEUTRAL", "buys": 0, "sells": 0 } }, // ... 9 more results ] } } } ``` ### Usage Guidelines * **ID formats**: * Trader ID: `
:` (e.g., `0x019782cab5d844f02bafb71f512758be78579f3c:Polymarket`) * Market ID: `:::` (e.g., `0xc65e24cc10c071c4643186287441624cb41040a3c66a2971e5fc44479cc25146:Polymarket:0xc5d563a36ae78145c45a50134d48a1215220f80a:137`) * Event ID: `:::` (e.g., `67284:Polymarket:0xc5d563a36ae78145c45a50134d48a1215220f80a:137`) * Default 100 results per request; `limit` accepts up to 200. * Use `traderIds` to track specific traders across markets, or `marketIds` to see all traders in specific markets * Filter by `hasOpenPosition: true` to find active positions, or `false` for closed positions only * Use `eventIds` to see trader activity across all markets within an event * PnL metrics (`totalRealizedPnlUsd`, `pnlPerVolumeMarket`) are only meaningful for resolved markets * Combine `outcome0PnlStatus` and `outcome1PnlStatus` filters to find winning or losing positions * Use `phrase` to search by trader alias, market label, or event label ### Understanding Trader-Market Records This query returns **trader-market pairs** - the performance of individual traders on specific markets: * **One record per trader-market combination** - if a trader traded on 10 markets, there are 10 records * **Aggregated across all trades** - `totalVolumeUsd`, `totalTrades`, `totalBuys`, `totalSells` sum up all activity * **Separate outcome data** - `outcome0` and `outcome1` show position details for each side Use this query to: * Track individual trader performance on specific markets * Find which traders profited most on particular events * Identify traders with open positions in markets of interest * Analyze trading patterns (buy/sell ratios, average entry prices) ### PnL Status Values See the [`PredictionTraderMarketPnlStatus`](https://docs.codex.io/api-reference/enums/predictiontradermarketpnlstatus) enum for all possible PnL status values and their meanings. ### Troubleshooting Tips > [accordion] What's the difference between totalRealizedPnlUsd and outcome PnL? > > `totalRealizedPnlUsd` is the sum of realized PnL across both outcomes. Individual outcome PnL (`outcome0.realizedPnlUsd`, `outcome1.realizedPnlUsd`) shows profit/loss for each side. Traders often trade both sides, so check both outcomes to understand their full strategy. > [accordion] What does pnlPerVolumeMarket tell me? > > This is the profit-to-volume ratio, showing how efficiently a trader extracted profit relative to their trading volume. A value of 0.15 means they made $0.15 profit per $1 traded. Higher values indicate more skilled trading or better market timing. > [accordion] Why is sharesHeld not zero even though the market is resolved? > > Some traders may not have sold their winning shares yet. On resolved markets, winning shares can be redeemed for \$1 each. Check `isWinningOutcome` to see if held shares are valuable or worthless. > [accordion] What's the difference between buys/sells counts and volume? > > `totalBuys` and `totalSells` count the number of transactions, while `totalVolumeUsd` measures the dollar value. A trader with 100 small trades might have less volume than one with 5 large trades. Use `profitPerTradeUsd` to measure per-transaction efficiency. ### Related Recipes * [Prediction Traders](https://docs.codex.io/recipes/predictions/traders.md): Show a trader's open positions, per-market P\&L, and top traders for a market or event This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.