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.

Subscriptions (WebSockets) require a Growth or Enterprise plan. Learn more.
This endpoint requires a Growth or Enterprise plan. Learn more.

​
Returns

​
Arguments

subscription {
  onHoldersUpdated(
    tokenId: "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2:1"
  ) {
    holders
    tokenId
    tokenAddress
    networkId
    balances {
      address
      balance
      shiftedBalance
      balanceUsd
      tokenPriceUsd
      firstHeldTimestamp
    }
  }
}
Example Response
{
  "data": {
    "onHoldersUpdated": {
      "holders": 3208982,
      "tokenId": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2:1",
      "tokenAddress": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      "networkId": 1,
      "balances": [
        {
          "address": "0x7773538f830bea99e8f6f222d019622764f0d426",
          "balance": "1638817141369641256",
          "shiftedBalance": 1.6388171413696413,
          "balanceUsd": null,
          "tokenPriceUsd": null,
          "firstHeldTimestamp": null
        }
        // ... 9 more balances
      ]
    }
  }
}

​
Usage Guidelines

  • Subscribe using tokenId in the format tokenAddress:networkId
  • holders returns the total unique count of wallets holding the token
  • balances array contains details for wallets whose balances changed
  • Use shiftedBalance for human-readable token amounts (adjusted for decimals)
  • firstHeldTimestamp shows when the wallet first acquired the token
  • Updates are triggered when any holder’s balance changes

​
Troubleshooting Tips

Updates are sent whenever a wallet’s token balance changes - through buys, sells, transfers, or any other on-chain movement of the token.
No, balances only includes wallets whose balances changed in the update. Use holders for the total count of unique holders.
balance is the raw token amount (including all decimals). shiftedBalance divides by the token’s decimals for readability. For example, 1.5 ETH would have balance “1500000000000000000” and shiftedBalance 1.5.
balanceUsd requires a valid token price. For very new tokens or those without sufficient liquidity, the USD value may not be available.
  • Detailed Token Page: Build a comprehensive token detail page with price, holders, trades, and real-time updates