onHoldersUpdated

This endpoint requires a Growth or Enterprise plan. Learn more.

Returns

HoldersUpdate

See HoldersUpdate

Show Properties

Int!

The number of different wallets holding the token.

String!

The ID of the token (tokenAddress:networkId).

String!

The token’s contract address.

Int!

The network ID that the token is deployed on.

[Balance!]!

The list of wallets holding the token. See Balance

Arguments

String!

required

Example

Test this query in the Explorer →

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

What triggers an update?

Updates are sent whenever a wallet’s token balance changes - through buys, sells, transfers, or any other on-chain movement of the token.

Does balances include all holders?

No, balances only includes wallets whose balances changed in the update. Use holders for the total count of unique holders.

What's the difference between balance and shiftedBalance?

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.

Why might balanceUsd be null?

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

⌘I

API Documentation

Queries

Mutations

Subscriptions

Types

onHoldersUpdated

Returns

Arguments

Example

Usage Guidelines

Troubleshooting Tips

​Returns

​Arguments

​Example

​Usage Guidelines

​Troubleshooting Tips

​Related Recipes

Returns

Arguments

Example

Usage Guidelines

Troubleshooting Tips

Related Recipes