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.
This endpoint only works with Polymarket. Token holder data is only available for Polymarket because it operates on-chain using ERC-1155 tokens on Polygon. Kalshi is a centralized exchange and does not have publicly queryable token holder information.
This endpoint requires a Growth or Enterprise plan. Learn more.

​
Returns

​
PredictionTokenHoldersConnection
PredictionTokenHoldersConnection
See PredictionTokenHoldersConnection

​
Arguments

​
input
PredictionTokenHoldersInput!
required
Input parameters used to select the market/token and pagination settings. See PredictionTokenHoldersInput

​
Example: Get top token holders for a prediction market

{
  predictionTokenHolders(
    input: {
      marketId: "0x9b6fef249040fd17e9c107955b37ac2c3e923509b6b0ff01cc463a331ddeb894:Polymarket:0xc5d563a36ae78145c45a50134d48a1215220f80a:137"
      tokenId: "108233603819467706476318984012158651931658302669301887462181073562758483842092"
      limit: 10
    }
  ) {
    items {
      walletAddress
      amount
      predictionTrader {
        alias
        totalTradesCount
        totalVolumeUsd
        allTimeProfitUsd
      }
    }
    total
  }
}
Example Response
{
  "data": {
    "predictionTokenHolders": {
      "items": [
        {
          "walletAddress": "0x1ede425ac39b1286e42174e8f97dfa0ea76b46e8",
          "amount": "501075.840000",
          "predictionTrader": {
            "alias": "67BrainRot",
            "totalTradesCount": 10143,
            "totalVolumeUsd": "10057571.278006",
            "allTimeProfitUsd": "-18863.446031"
          }
        },
        {
          "walletAddress": "0x8ba27b7c9de2b6367f986bff5f9c8049204c1650",
          "amount": "363428.719893",
          "predictionTrader": {
            "alias": null,
            "totalTradesCount": 156,
            "totalVolumeUsd": "418765.058632",
            "allTimeProfitUsd": "47521.718629"
          }
        },
        {
          "walletAddress": "0xe9076a87c5ed90ef16e6fe6529c943baeca0cff6",
          "amount": "339259.206526",
          "predictionTrader": {
            "alias": null,
            "totalTradesCount": 892096,
            "totalVolumeUsd": "28003216.849224",
            "allTimeProfitUsd": "-152027.731686"
          }
        },
        // ... 7 more token holders
      ],
      "total": 14970
    }
  }
}

​
Usage Guidelines

  • Market ID format:
    • Polymarket: <marketAddress>:Polymarket:<exchangeAddress>:<networkId> (e.g., 0x25aa90b3cd98305e849189b4e8b770fc77fe89bccb7cf9656468414e01145d38:Polymarket:0xc5d563a36ae78145c45a50134d48a1215220f80a:137)
    • Kalshi: <marketSlug>:Kalshi (e.g., KXMVECROSSCATEGORY-S2026A4A05B370DF-F1FBA451AA9:Kalshi)
  • Getting token IDs: Query a market using predictionMarkets and retrieve the outcomeIds array. Each outcomeId is a compound string (e.g., 46553...232024:Polymarket:0xc5d5...80a:137). The tokenId is the first segment before the first colon (e.g., 46553...232024). For binary markets, outcomeIds[0] is “Yes” and outcomeIds[1] is “No”.
  • Token holder sorting: Results are sorted by amount in descending order (largest holders first)
  • Trader profiles: The predictionTrader field may be null if the wallet address hasn’t been indexed as a trader (always null for Kalshi, though Kalshi markets don’t support this endpoint)
  • Pagination: Returns paginated results - use cursor for pagination through large holder lists

​
Understanding Token Holder Data

  • Amounts are returned as strings to preserve precision for large numbers
  • predictionTrader will be null for wallets that only hold tokens but haven’t placed trades
  • Results are sorted by token amount (highest balances first)

​
Troubleshooting Tips

The predictionTrader field is only populated for wallets that have been indexed as active traders with trading history. Wallets that only received tokens through transfers (not trades) or very new wallets may not have an associated trader profile yet. These holders will show walletAddress and amount but have null for predictionTrader.
The amount field represents the raw token balance in the smallest unit (similar to wei for ETH). For Polymarket, these are typically 18-decimal precision numbers. To convert to a human-readable format, divide by 10^18. For example, “125000000000000000000” equals 125 tokens. Always use string parsing for precision to avoid JavaScript number overflow.
Yes, token holder balances are updated as trades occur on the blockchain. When tokens are bought, sold, or transferred, the holder balances reflect those changes. There may be a brief delay (typically seconds to minutes) as blocks are processed and indexed.
The API returns all token holders sorted by amount (largest first). To filter by minimum amount, fetch the results and filter client-side. Since results are sorted descending, once you encounter a holder below your threshold, you can stop pagination as all subsequent holders will have smaller amounts.
Binary markets (Yes/No) have two outcome tokens. You need to make two separate queries, one for each tokenId. Use the market’s outcomeIds array to get both outcome IDs, then extract the tokenId from each by taking the first segment before the colon (e.g., from 46553...232024:Polymarket:0xc5d5...80a:137, the tokenId is 46553...232024). Query predictionTokenHolders once for each.
This query returns holders for a specific token. To see all positions for a specific trader across markets, use predictionTraderMarketsStats with the trader’s ID (Polymarket only). That query returns per-market statistics including shares held for each outcome.
No. This endpoint only works for Polymarket because Kalshi is a centralized exchange that doesn’t expose token holder information. Polymarket uses on-chain ERC-1155 tokens on Polygon, making holder data publicly queryable.