onHoldersUpdated

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

Returns

HoldersUpdate

Show Properties

holders

Int!

required

The number of different wallets holding the token.

tokenId

String!

required

The ID of the token (tokenAddress:networkId).

tokenAddress

String!

required

The token’s contract address.

networkId

Int!

required

The network ID that the token is deployed on.

balances

[Balance!]!

required

The list of wallets holding the token.

Show Properties

walletId

String!

required

The ID of the wallet (walletAddress:networkId).

tokenId

String!

required

The ID of the token (tokenAddress:networkId).

address

String!

required

The wallet address.

networkId

Int!

required

The wallet network.

tokenAddress

String!

required

The contract address of the token.

balance

String!

required

The balance held by the wallet.

shiftedBalance

Float!

required

The balance held by the wallet, adjusted by the number of decimals in the token.

balanceUsd

String

The balance held by the wallet in USD.

tokenPriceUsd

String

The token price in USD.

firstHeldTimestamp

Int

The time that this address first held a token.

token

EnhancedToken

Metadata for the token.

Show Properties

address

String!

required

The contract address of the token.

cmcId

Int

The token ID on CoinMarketCap.

decimals

Int!

required

The precision to which the token can be divided. For example, the smallest unit for USDC is 0.000001 (6 decimals).

String!

required

The ID of the token (address:networkId).

isScam

Boolean

Whether the token has been flagged as a scam.

name

String

The token name. For example, ApeCoin.

networkId

Int!

required

The network ID the token is deployed on.

symbol

String

The token symbol. For example, APE.

socialLinks

SocialLinks

Community gathered links for the socials of this token.

Show Properties

bitcointalk

String

blog

String

coingecko

String

coinmarketcap

String

discord

String

facebook

String

github

String

instagram

String

slack

String

twitch

String

twitter

String

website

String

wechat

String

whitepaper

String

youtube

String

info

TokenInfo

More metadata about the token.

Show Properties

String!

required

Uniquely identifies the token.

address

String!

required

The contract address of the token.

circulatingSupply

String

The circulating supply of the token.

cmcId

Int

The token ID on CoinMarketCap.

isScam

Boolean

Whether the token has been flagged as a scam.

name

String

The token name. For example, ApeCoin.

networkId

Int!

required

The network ID the token is deployed on.

symbol

String!

required

The token symbol. For example, APE.

totalSupply

String

The total supply of the token.

imageThumbHash

String

The thumbhash of the token logo.

imageThumbUrl

String

The thumbnail token logo URL.

imageSmallUrl

String

The small token logo URL.

imageLargeUrl

String

The large token logo URL.

imageBannerUrl

String

The token banner URL.

videoExternalUrl

String

The original URL/URI for the video associated with the token.

description

String

A description of the token.

exchanges

[Exchange!]

A list of exchanges where the token has been traded.

Show Properties

address

String!

required

The contract address of the exchange.

color

String

The hex string for the exchange color.

String!

required

The ID of the exchange (address:id).

name

String

The name of the exchange.

exchangeVersion

String

The version of the exchange, if applicable.

iconUrl

String

The exchange logo URL.

networkId

Int!

required

The network ID the exchange is deployed on.

tradeUrl

String

The URL for the exchange.

creatorAddress

String

The token creator’s wallet address.

createBlockNumber

Int

The block height the token was created at.

createTransactionHash

String

The transaction hash of the token’s creation.

createdAt

Int

The unix timestamp for the creation of the token.

mintable

String

Returns mint authority address if token is mintable. If null, verify against isMintableValid.

freezable

String

Returns freeze authority address if token is freezable. If null, verify against isFreezableValid.

isFreezableValid

Boolean

Determines if freezable is a valid address or null value for the authority, or if the freezable state has not yet been determined.

isMintableValid

Boolean

Determines if mintable is a valid address or null value for the authority, or if the mintable state has not yet been determined.

launchpad

LaunchpadData

The launchpad data for the token, if applicable.

Show Properties

launchpadName

String

The name of the launchpad.

graduationPercent

Float

The percentage of the pool that was sold to the public.

poolAddress

String

The address of the pool.

completedAt

Int

The unix timestamp when the launchpad was completed.

completed

Boolean

Indicates if the launchpad is completed.

completedSlot

Int

The slot number when the launchpad was completed.

migratedSlot

Int

The slot number when the launchpad was migrated.

migratedAt

Int

The unix timestamp when the launchpad was migrated.

migrated

Boolean

Indicates if the launchpad was migrated.

migratedPoolAddress

String

The pool address after the launchpad was migrated.

launchpadProtocol

String

The launchpad protocol.

launchpadIconUrl

String

The icon URL of the launchpad.

name

String

deprecated

The name of the launchpad.

This field is deprecated. Use launchpadName instead

totalSupply

String

deprecated

The total supply of the token.

This field is deprecated. Use the TokenInfo type

explorerData

ExplorerTokenData

deprecated

Information about the token from 3rd party sources.

This field is deprecated. Use the TokenInfo type

Show Properties

String!

required

The ID of the token (address:networkId).

blueCheckmark

Boolean

Whether the token has been verified on CoinGecko.

description

String

A description of the token.

divisor

String

The precision to which the token can be divided.

tokenPriceUSD

String

The token price in USD.

tokenType

String

The token type.

imageThumbUrl

String

deprecated

The thumbnail token logo URL.

This field is deprecated. Use the TokenInfo type

imageSmallUrl

String

deprecated

The small token logo URL.

This field is deprecated. Use the TokenInfo type

imageLargeUrl

String

deprecated

The large token logo URL.

This field is deprecated. Use the TokenInfo type

circulatingSupply

String

deprecated

The circulating supply of the token.

This field is deprecated. Use the TokenInfo type

pooled

String

deprecated

The amount of this token in the pair.

This field is deprecated. Pooled can be found on the pair instead

liquidityUsd

String

The liquidity of the token in USD.

Arguments

tokenId

String!

required

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.

API Documentation

Queries

Mutations

Subscriptions

Types

onHoldersUpdated

Returns

Arguments

Usage Guidelines

Troubleshooting Tips

API Documentation

Queries

Mutations

Subscriptions

Types

​Returns

​Arguments

​Usage Guidelines

​Troubleshooting Tips

Returns

Arguments

Usage Guidelines

Troubleshooting Tips