EVM Token Holders API

Query-only

A subscription on Holders is accepted but never pushes a message. Poll it on a schedule, and stream Transfers for the token to know when a refresh is worthwhile. See which cubes support subscriptions.

The Holders API returns token holder data for ERC-20 tokens: top holders, holder counts, and balance thresholds. Non-zero balances use Amount(selectWhere: { gt: "0" }) on the Balance field (not in where). Use dataset: combined or dataset: archive as follows:

Dataset	When to use
combined	Latest holder count, top holders, and balances. Queries realtime and archive databases and merges results.
archive	Addresses not recently active (not in the realtime window).

Full Ethereum examples: Token Holders API.

Token holder count

query {
  EVM(network: eth, dataset: combined) {
    Holders(
      where: {
        Currency: {
          SmartContract: {
            is: "0x54D2252757e1672EEaD234D27B1270728fF90581"
          }
        }
      }
    ) {
      uniq(of: Holder_Address)
    }
  }
}

Filter parameters

• dataset: combined — latest holder count, top holders, and activity
• dataset: archive — addresses not recently active
• where.Currency.SmartContract — token contract address (required)
• where.Balance.LastChangeTime — filter by last balance change (datetime, e.g. till: "2026-05-01T00:00:00Z"). The Holders cube does not support Block.Date.
• where.Holder.Address — filter to a specific wallet
• Balance.Amount(selectWhere: { gt: "..." }) — non-zero balances when listing amounts
• uniq(of: Holder_Address, if: { Balance: { Amount: { gt: "..." } } } }) — holder count above a threshold
• limit, orderBy — pagination and sorting (e.g. descending: Balance_Amount)

Return fields

• Holder.Address — holder wallet address
• Balance.Amount, Balance.AmountInUSD — token balance (use selectWhere for non-zero)
• Balance.UpdateCount, Balance.FirstChangeTime, Balance.LastChangeTime — holder activity

Examples on Ethereum

• Top holders (current)
• Token holder count
• Holder count above a threshold
• Track whale wallets
• Historical top holders
• Holder count history
• Wallet token balance at a date (via Balances API)
• Holder activity — UpdateCount, FirstChangeTime, LastChangeTime