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
}
}
}
}