Skip to main content
Subscriptions (WebSockets) require 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.