Token Holders API
EVM.TokenHolders is deprecated as of 20 May 2026 and will be removed on 15 June 2026. Use EVM.Holders (this page) instead.
The Holders API returns token holder data for ERC-20 tokens on Ethereum: 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). |
Examples: Top Holders · Holder Count · Whales · Historical Top Holders · Holder Activity · Statistics
Top Holders of a Currency (Current)
The most common starting point for traders and analysts: who holds the most of a token right now. Use dataset: combined for the latest top holders (realtime + archive).
Click to expand GraphQL query
query {
EVM(network: eth, dataset: combined) {
Holders(
where: {
Currency: {
SmartContract: {
is: "0x54D2252757e1672EEaD234D27B1270728fF90581"
}
}
}
orderBy: {
descending: Balance_Amount
}
limit: {
count: 10
}
) {
Holder {
Address
}
Balance {
Amount(selectWhere: { gt: "0" })
FirstChangeTime
LastChangeTime
}
}
}
}
Token Holder Count for an ERC-20 Token
How many wallets hold a token. Count distinct addresses with uniq(of: Holder_Address) and dataset: combined.
Click to expand GraphQL query
query {
EVM(network: eth, dataset: combined) {
Holders(
where: {
Currency: {
SmartContract: {
is: "0x54D2252757e1672EEaD234D27B1270728fF90581"
}
}
}
) {
uniq(of: Holder_Address)
}
}
}
Token Holder Snapshot
The number of unique holders, token supply, and Gini coefficient for the balance amount before a specific timestamp can be derived using the query below. These stats provide a useful holder snapshot for any given time.
Click to expand GraphQL query
query MyQuery($network: evm_network!, $address: String!) {
EVM(network: $network, dataset: archive) {
Holders(
where: {
Currency: {SmartContract: {is: $address}},
Balance: {
Amount: {gt: "0"},
LastChangeTime: {till: "2026-05-20T00:00:00Z"}
},
Holder: {Address: {not: "0x"}}}
) {
Balance {
LastChangeTime(maximum: Balance_LastChangeTime)
}
holders: uniq(of: Holder_Address)
supply: sum(of: Balance_Amount)
gini(of: Balance_Amount)
}
}
}
{
"network": "eth",
"address": "0x00000000001594c61dd8a6804da9ab58ed2483ce"
}
Holder Count with Balance Above a Threshold
Count holders above a minimum balance (whale / large-holder filters). Use uniq(of: Holder_Address, if: { Balance: { Amount: { gt: "..." } } }) with your threshold.
Click to expand GraphQL query
query {
EVM(network: eth, dataset: combined) {
Holders(
where: {
Currency: {
SmartContract: {
is: "0x54D2252757e1672EEaD234D27B1270728fF90581"
}
}
}
) {
uniq(
of: Holder_Address
if: {
Balance: {
Amount: {
gt: "10000000"
}
}
}
)
}
}
}
Track Whale Wallets and Token Holdings
For whale monitoring, combine Top Holders (orderBy: { descending: Balance_Amount }, limit) with Holder Count Above a Threshold. Pair with ERC-20 transfers to see recent inflows and outflows from large wallets.
Historical Top Holders by Date
The Holders cube does not support Block.Date. Filter by Balance.LastChangeTime using datetime format (for example "2026-05-01T00:00:00Z"). For address balances on a calendar date, use the Balances API with Block.Date.
Click to expand GraphQL query
query {
EVM(network: eth, dataset: combined) {
Holders(
where: {
Balance: {
LastChangeTime: {
till: "2026-05-01T00:00:00Z"
}
}
Currency: {
SmartContract: {
is: "0x54D2252757e1672EEaD234D27B1270728fF90581"
}
}
}
orderBy: {
descending: Balance_Amount
}
limit: {
count: 100
}
) {
Holder {
Address
}
Balance {
Amount(selectWhere: { gt: "0" })
LastChangeTime
}
}
}
}
Token Holder Count History Over Time
Build holder-count time series by running the count query with Balance.LastChangeTime.till at different timestamps, then aggregating in your app or scheduler.
Click to expand GraphQL query
query {
EVM(network: eth, dataset: combined) {
Holders(
where: {
Balance: {
LastChangeTime: {
till: "2026-05-01T00:00:00Z"
}
}
Currency: {
SmartContract: {
is: "0x54D2252757e1672EEaD234D27B1270728fF90581"
}
}
}
) {
uniq(of: Holder_Address)
}
}
}
Wallet Balance at a Point in Time
One wallet’s balance for a token on a given date uses the Balances API, not Holders: set Balance.Address, Currency.SmartContract, and Block.Date.till. Use dataset: archive, orderBy: { descending: Block_Date }, and limit: { count: 1 }.
Run in IDE · Balances API docs
Click to expand GraphQL query
query {
EVM(network: eth, dataset: archive) {
Balances(
where: {
Block: {
Date: {
till: "2026-05-05"
}
}
Balance: {
Address: {
is: "0xA46320Aa0b4877b9a46a07B4F3DB93719bd422dE"
}
}
Currency: {
SmartContract: {
is: "0x54D2252757e1672EEaD234D27B1270728fF90581"
}
}
}
limit: {
count: 1
}
orderBy: {
descending: Block_Date
}
) {
Currency {
Symbol
SmartContract
}
Balance {
Amount(selectWhere: { gt: "0" })
AmountInUSD
Address
}
}
}
}
Token Holder Activity
Drill into a specific wallet for a token: transfer count and first/last activity times. Uses the Holders API (UpdateCount, FirstChangeTime, LastChangeTime).
Count of Transactions for a Token from a Token Holder
Click to expand GraphQL query
query {
EVM(network: eth, dataset: combined) {
Holders(
where: {
Currency: {
SmartContract: {
is: "0x54D2252757e1672EEaD234D27B1270728fF90581"
}
}
Holder: {
Address: {
is: "0xB953E202C5E51C7C010E80402a63C02f37F14059"
}
}
}
) {
Balance {
UpdateCount
}
}
}
}
First and Last Transfer Dates for a Token Holder
Click to expand GraphQL query
query {
EVM(network: eth, dataset: combined) {
Holders(
where: {
Currency: {
SmartContract: {
is: "0x54D2252757e1672EEaD234D27B1270728fF90581"
}
}
Holder: {
Address: {
is: "0xB953E202C5E51C7C010E80402a63C02f37F14059"
}
}
}
) {
Balance {
UpdateCount
LastChangeTime
FirstChangeTime
}
}
}
}
Token Holder Statistics
Distribution metrics (average, median, Gini, Nakamoto index, and more) via the legacy TokenHolders cube or aggregated Holders queries. See statistics docs for the full metric list.
Average Balance of a Token Holder
Click to expand GraphQL query
{
EVM(dataset: archive, network: eth) {
TokenHolders(
date: "2026-05-01"
tokenSmartContract: "0xdAC17F958D2ee523a2206206994597C13D831ec7"
where: { Balance: { Amount: { ge: "0" } } }
) {
average(of: Balance_Amount)
}
}
}
Median Balance of a Token Holder
Click to expand GraphQL query
{
EVM(dataset: archive, network: eth) {
TokenHolders(
date: "2026-05-01"
tokenSmartContract: "0xdAC17F958D2ee523a2206206994597C13D831ec7"
where: { Balance: { Amount: { ge: "0" } } }
) {
median(of: Balance_Amount)
}
}
}
Find Token Holders Outside a Certain Range
Advanced filter: holders with balance above an upper bound or below a lower bound (e.g. excluding mid-tier wallets).
Click to expand GraphQL query
{
EVM(dataset: archive) {
TokenHolders(
tokenSmartContract: "0x0fcbd68251819928c8f6d182fc04be733fa94170"
date: "2026-05-01"
where: {
any: [
{ Balance: { Amount: { gt: "100" } } }
{ Balance: { Amount: { lt: "20" } } }
]
Balance: { Amount: { gt: "0" } }
}
orderBy: { descending: Balance_Amount }
limit: { count: 10 }
) {
Balance {
Amount
}
Holder {
Address
}
Currency {
Name
Symbol
}
}
}
}