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.

Prediction Market data is currently in beta. It is actively being worked on and improved, but may be unreliable. Polymarket and Kalshi data are live.At least for the time being, this endpoint requires a Growth or Enterprise plan. Learn more.
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.
This endpoint requires a Growth or Enterprise plan. Learn more.

​
Returns

​
PredictionTraderMarketFilterConnection
PredictionTraderMarketFilterConnection
See PredictionTraderMarketFilterConnection

​
Arguments

​
filters
PredictionTraderMarketFilters
A set of filters to apply. See PredictionTraderMarketFilters
​
phrase
String
A phrase to search for. Can match trader alias, market label, or event label.
​
traderIds
[String!]
A list of trader IDs to filter by.
​
excludeTraderIds
[String!]
A list of trader IDs to exclude from results.
​
marketIds
[String!]
A list of market IDs to filter by.
​
excludeMarketIds
[String!]
A list of market IDs to exclude from results.
​
eventIds
[String!]
A list of event IDs to filter by (returns records for markets in these events).
​
excludeEventIds
[String!]
A list of event IDs to exclude.
​
rankings
[PredictionTraderMarketRanking!]
A list of ranking attributes to apply. See PredictionTraderMarketRanking
​
limit
Int
The maximum number of results to return.
​
offset
Int
Where in the list the server should start when returning items.

​
Example: Top profitable trader positions

{
  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
      }
    }
  }
}
Example Response (truncated)
{
  "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: <address>:<protocol> (e.g., 0x019782cab5d844f02bafb71f512758be78579f3c:Polymarket)
    • Market ID: <marketAddress>:<protocol>:<eventAddress>:<networkId> (e.g., 0xc65e24cc10c071c4643186287441624cb41040a3c66a2971e5fc44479cc25146:Polymarket:0xc5d563a36ae78145c45a50134d48a1215220f80a:137)
    • Event ID: <venueId>:<protocol>:<eventAddress>:<networkId> (e.g., 67284:Polymarket:0xc5d563a36ae78145c45a50134d48a1215220f80a:137)
  • Response limit: 100 trader-market records per request (configurable with limit parameter)
  • 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 enum for all possible PnL status values and their meanings.

​
Troubleshooting Tips

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.
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.15profitper0.15 profit per 1 traded. Higher values indicate more skilled trading or better market timing.
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.
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.
  • Prediction Traders: Show a trader’s open positions, per-market P&L, and top traders for a market or event