Token Holders API
The Token Holders API allows you to access information regarding token holders for both fungible (ERC20) and non-fungible (ERC721) tokens. This API provides access to current token holder data for a specific token, as well as historical information about token holders.
Let's explore some examples and discover how to use the Token Holders API.
Total Token Holder Count
With the Token Holders API, you can retrieve the total number of token holders by using the uniq field on Holder_Address. In this example, we query the USDT holders on Ethereum as of October 21, 2023:
You can run this query in our IDE: USDT token holder count
Click to expand GraphQL query
{
EVM(dataset: archive, network: eth) {
TokenHolders(
date: "2023-10-21"
tokenSmartContract: "0xdAC17F958D2ee523a2206206994597C13D831ec7"
where: { Balance: { Amount: { gt: "0" } } }
) {
uniq(of: Holder_Address)
}
}
}
Token holders of a token
Get all token holders for a given token on a specific date. Adjust limit as needed:
Run in IDE: Token holder API
Click to expand GraphQL query
{
EVM(dataset: archive, network: eth) {
TokenHolders(
date: "2024-03-01"
tokenSmartContract: "0x60E4d786628Fea6478F785A6d7e704777c86a7c6"
limit: { count: 100 }
orderBy: { descending: Balance_Amount }
) {
Holder {
Address
}
Balance {
Amount
}
}
}
}
Token Balance of an address on a particular date
Find how many tokens a specific address held on a given date:
Run in IDE: Balance of token holder
Click to expand GraphQL query
{
EVM(dataset: archive, network: eth) {
TokenHolders(
date: "2023-10-01"
tokenSmartContract: "0x60E4d786628Fea6478F785A6d7e704777c86a7c6"
where: {
Holder: {
Address: { is: "0x50d9090d6ce6307b7ec8904cd3dca17b4da56353" }
}
}
) {
Holder {
Address
}
Balance {
Amount
}
}
}
}
Token Holders Over Time
To track holder counts over a range of dates, repeat the TokenHolders query with different date values to build your time series.
Token Holder Activity
Count of Transactions for a Token from a Token Holder
See how many on-chain transactions a given address made involving a specific token:
Run in IDE: Number of token transactions for a wallet
Click to expand GraphQL query
{
EVM(dataset: archive, network: eth) {
TokenHolders(
date: "2023-10-22"
tokenSmartContract: "0x60E4d786628Fea6478F785A6d7e704777c86a7c6"
where: {
Holder: {
Address: { is: "0x18f024244d0c41534c4fb77f958912f3aa403719" }
}
}
) {
BalanceUpdate {
transactions: Count
}
Holder {
Address
}
}
}
}
First & Last Date of Transfer for a Token Holder
Retrieve the first and most recent transfer dates for a holder:
Run in IDE: First & last date of transfer
Click to expand GraphQL query
{
EVM(dataset: archive, network: eth) {
TokenHolders(
date: "2023-10-22"
tokenSmartContract: "0x60E4d786628Fea6478F785A6d7e704777c86a7c6"
where: {
Holder: {
Address: { is: "0x18f024244d0c41534c4fb77f958912f3aa403719" }
}
}
) {
BalanceUpdate {
FirstDate
LastDate
}
Holder {
Address
}
}
}
}
Amount In & Out for a Wallet
Check total tokens received and sent by a holder:
Run in IDE: Received and sent tokens
Click to expand GraphQL query
{
EVM(dataset: archive, network: eth) {
TokenHolders(
date: "2023-10-22"
tokenSmartContract: "0x60E4d786628Fea6478F785A6d7e704777c86a7c6"
where: {
Holder: {
Address: { is: "0x18f024244d0c41534c4fb77f958912f3aa403719" }
}
}
) {
BalanceUpdate {
InAmount
OutAmount
}
Holder {
Address
}
}
}
}
Top Token Holders for a Token
Find the top 10 holders by balance:
Run in IDE: Top token holders
Click to expand GraphQL query
{
EVM(dataset: archive, network: eth) {
TokenHolders(
date: "2023-10-22"
tokenSmartContract: "0x60E4d786628Fea6478F785A6d7e704777c86a7c6"
limit: { count: 10 }
orderBy: { descending: Balance_Amount }
) {
Holder {
Address
}
Balance {
Amount
}
}
}
}
Token Holder with Certain Number of Tokens
Find how many holders exceed a threshold:
Run in IDE: Count of holders above certain value
Click to expand GraphQL query
{
EVM(dataset: archive, network: eth) {
TokenHolders(
date: "2023-10-22"
tokenSmartContract: "0x23581767a106ae21c074b2276D25e5C3e136a68b"
where: { Balance: { Amount: { ge: "50" } } }
) {
uniq(of: Holder_Address)
}
}
}
Here’s another example grouping USDT holders into tiers using aliases:
Run in IDE: USDT token holder distribution
Click to expand GraphQL query
{
EVM(dataset: archive, network: eth) {
TokenHolders(
date: "2023-10-22"
tokenSmartContract: "0xdAC17F958D2ee523a2206206994597C13D831ec7"
where: { Balance: { Amount: { ge: "0" } } }
) {
classic: count(
distinct: Holder_Address
if: { Balance: { Amount: { gt: "1000000" } } }
)
pro: count(
distinct: Holder_Address
if: { Balance: { Amount: { gt: "100000", le: "1000000" } } }
)
growing: count(
distinct: Holder_Address
if: { Balance: { Amount: { gt: "1000", le: "100000" } } }
)
}
}
}
Top Trending Tokens Based on Token Holders using BalanceUpdates API
Identify the top 10 trending tokens by holder growth:
Run in IDE: Trending tokens by holders
Click to expand GraphQL query
query MyQuery {
EVM(network: eth, dataset: combined) {
BalanceUpdates(
where: {
Block: { Date: { since: "2023-06-01" } }
BalanceUpdate: { Amount: { gt: "0" } }
}
orderBy: { descendingByField: "No_Holders" }
limit: { count: 10 }
) {
No_Holders: count(distinct: BalanceUpdate_Address)
Currency {
Name
SmartContract
}
}
}
}
Top Token Holders of a specific Token using BalanceUpdates API
Get the top 10 holders for a particular token via the BalanceUpdates API:
Run in IDE: Top 10 token holders of a specific token
Click to expand GraphQL query
query MyQuery {
EVM(network: eth, dataset: combined) {
BalanceUpdates(
limit: { count: 10 }
orderBy: { descendingByField: "Balance" }
where: {
Currency: {
SmartContract: { is: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48" }
}
}
) {
Balance: sum(of: BalanceUpdate_Amount)
Currency {
SmartContract
Name
Symbol
}
BalanceUpdate {
Address
}
}
}
}
Or get native ETH top holders on a particular date:
Run in IDE: Top native ETH holders
Click to expand GraphQL query
{
EVM(dataset: archive, network: eth) {
TokenHolders(
date: "2024-03-01"
limit: { count: 100 }
orderBy: { descending: Balance_Amount }
where: { Currency: { Native: true } }
tokenSmartContract: "0x"
) {
Holder {
Address
}
Balance {
Amount
}
}
}
}
Common Token Holders of Two Tokens
Find addresses holding both BAYC and MAYC NFTs:
Run in IDE: Common token holder – BAYC & MAYC
Click to expand GraphQL query
{
EVM(dataset: archive) {
BalanceUpdates(
orderBy: { descendingByField: "token1" }
limit: { count: 1000 }
where: {
Currency: {
SmartContract: {
in: [
"0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d"
"0x60e4d786628fea6478f785a6d7e704777c86a7c6"
]
}
}
}
) {
BalanceUpdate {
Address
}
token1: sum(
of: BalanceUpdate_Amount
if: {
Currency: {
SmartContract: { is: "0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d" }
}
}
selectWhere: { gt: "0" }
)
token2: sum(
of: BalanceUpdate_Amount
if: {
Currency: {
SmartContract: { is: "0x60e4d786628fea6478f785a6d7e704777c86a7c6" }
}
}
selectWhere: { gt: "0" }
)
}
}
}
Token Holder Statistics
The Token Holders API provides built-in metrics. See statistics docs for the full list.
Average Balance of Token Holder
Calculate the average USDT balance across all holders on October 22, 2023:
Run in IDE: Average USDT balance
Click to expand GraphQL query
{
EVM(dataset: archive, network: eth) {
TokenHolders(
date: "2023-10-22"
tokenSmartContract: "0xdAC17F958D2ee523a2206206994597C13D831ec7"
where: { Balance: { Amount: { ge: "0" } } }
) {
average(of: Balance_Amount)
}
}
}
Median Balance of Token Holder
Compute the median balance for USDT holders on the same date:
Run in IDE: Median USDT balance
Click to expand GraphQL query
{
EVM(dataset: archive, network: eth) {
TokenHolders(
date: "2023-10-22"
tokenSmartContract: "0xdAC17F958D2ee523a2206206994597C13D831ec7"
where: { Balance: { Amount: { ge: "0" } } }
) {
median(of: Balance_Amount)
}
}
}
Token Liquidation: Finding Complete Holdings Transfers
Identify users who transferred out all of their DAI on March 22, 2023:
Run in IDE: Liquidated all DAI holdings
Click to expand GraphQL query
{
EVM(dataset: archive, network: eth) {
TokenHolders(
limit: { count: 100 }
tokenSmartContract: "0xdac17f958d2ee523a2206206994597c13d831ec7"
date: "2023-03-22"
where: {
BalanceUpdate: {
LastDate: { is: "2023-03-22" }
OutAmount: { gt: "0" }
}
Balance: { Amount: { eq: "0" } }
}
) {
Holder {
Address
}
BalanceUpdate {
OutAmount
}
}
}
}
Gini Coefficient
Compute the Gini coefficient for USDC distribution:
Run in IDE: Gini coefficient – USDC
Click to expand GraphQL query
{
EVM(dataset: archive, network: eth) {
TokenHolders(
date: "2023-10-22"
tokenSmartContract: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
where: { Balance: { Amount: { gt: "0" } } }
) {
gini(of: Balance_Amount)
}
}
}
Nakamoto Coefficient
Calculate the Nakamoto coefficient (99%) for stETH:
Run in IDE: Nakamoto coefficient – stETH
Click to expand GraphQL query
{
EVM(dataset: archive, network: eth) {
TokenHolders(
date: "2023-10-22"
tokenSmartContract: "0xae7ab96520DE3A18E5e111B5EaAb095312D7fE84"
where: { Balance: { Amount: { gt: "0" } } }
) {
nakamoto(of: Balance_Amount, ratio: 0.99)
}
}
}
Thiel Index
Obtain the Thiel index for stETH:
Run in IDE: Thiel index – stETH
Click to expand GraphQL query
{
EVM(dataset: archive, network: eth) {
TokenHolders(
date: "2023-10-22"
tokenSmartContract: "0xae7ab96520DE3A18E5e111B5EaAb095312D7fE84"
where: { Balance: { Amount: { gt: "0" } } }
) {
theil_index(of: Balance_Amount)
}
}
}
Find Token Holders Outside a Certain Range
Filter for holders with very large or very small balances:
Run in IDE: Find holders outside a range
Click to expand GraphQL query
{
EVM(dataset: archive) {
TokenHolders(
tokenSmartContract: "0x0fcbd68251819928c8f6d182fc04be733fa94170"
date: "2024-01-29"
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
}
}
}
}