The Token Holders API provides developers and analysts with comprehensive access to token holder information for both ERC20 (fungible) and ERC721 (non-fungible) tokens. This powerful tool enables real-time and historical analysis of blockchain ownership patterns across multiple networks.
Key Features of Token Holders API
- Real-time holder tracking - Monitor current token distribution
- Historical snapshot capability - Analyze holder data at any past date
- Multi-chain support - Works across Ethereum and compatible networks
- Advanced metrics - Includes statistical analysis tools
- Flexible querying - Customizable parameters for precise data retrieval
Total Token Holder Count Analysis
To determine the total number of unique holders for any token, use the uniq field on Holder_Address. This provides an accurate count of distinct wallet addresses holding the token.
Example Query:
query USDT_Holders {
EVM(dataset: archive, network: eth) {
TokenHolders(
date: "2023-10-21"
tokenSmartContract: "0xdac17f958d2ee523a2206206994597c13d831ec7"
) {
uniq(of: Holder_Address)
}
}
}👉 Learn more about holder analytics
Retrieving Comprehensive Holder Lists
Obtain complete lists of token holders with their respective balances:
query AllHolders {
EVM(dataset: archive, network: eth) {
TokenHolders(
date: "2023-10-21"
tokenSmartContract: "0xdac17f958d2ee523a2206206994597c13d831ec7"
limit: {count: 100}
) {
Holder {
Address
}
balance
}
}
}Historical Balance Tracking
The API enables precise historical balance checks for any address:
query HistoricalBalance {
EVM(dataset: archive, network: eth) {
TokenHolders(
date: "2023-10-21"
tokenSmartContract: "0xdac17f958d2ee523a2206206994597c13d831ec7"
where: {Holder: {Address: {is: "0x..."}}}
) {
balance
}
}
}Advanced Holder Analytics
Holder Activity Metrics
Track transaction patterns and wallet activity:
query HolderActivity {
EVM(dataset: archive, network: eth) {
Transfers(
where: {
Transfer: {
Receiver: {is: "0x..."}
OR: {Sender: {is: "0x..."}}
}
}
) {
count
first_date: min(of: Block_Time)
last_date: max(of: Block_Time)
}
}
}Top Holder Identification
Identify major stakeholders in any token ecosystem:
query TopHolders {
EVM(dataset: archive, network: eth) {
TokenHolders(
date: "2023-10-21"
tokenSmartContract: "0xdac17f958d2ee523a2206206994597c13d831ec7"
orderBy: {descending: balance}
limit: {count: 10}
) {
Holder {
Address
}
balance
}
}
}👉 Discover advanced holder tracking techniques
Statistical Analysis Tools
The API provides built-in statistical functions for deeper insights:
| Metric | Description | Use Case |
|---|---|---|
| Gini Coefficient | Measures token distribution inequality | Protocol health assessment |
| Nakamoto Coefficient | Concentration risk analysis | Security evaluation |
| Thiel Index | Alternative concentration metric | Economic analysis |
Example statistical query:
query TokenMetrics {
EVM(dataset: archive, network: eth) {
TokenHolders(
date: "2023-10-21"
tokenSmartContract: "0xdac17f958d2ee523a2206206994597c13d831ec7"
) {
statistics {
balance {
mean
median
}
}
}
}
}Common Use Cases
- Token distribution analysis - Understand holder concentration
- Airdrop targeting - Identify eligible wallets
- Governance participation tracking - Monitor voting power distribution
- Protocol health monitoring - Detect whale movements
- Compliance reporting - Track large holders for regulatory requirements
Frequently Asked Questions
How current is the holder data?
The API provides real-time data with typical update intervals under 5 minutes.
Can I track historical holder counts?
Yes, the API supports historical queries dating back to the token's creation.
What networks are supported?
The API currently supports Ethereum and compatible EVM chains.
How do I identify whale wallets?
Use the top holder queries sorted by descending balance.
Can I track NFT holders?
Yes, the API supports both ERC20 and ERC721 token standards.
What's the maximum query range?
Daily snapshots are available for any single date, with no inherent range limitation.
👉 Explore more blockchain analytics tools
Best Practices for Token Holder Analysis
- Regular snapshots - Track changes over time
- Combine with transfer data - Contextualize holder movements
- Monitor whale activity - Detect large transactions
- Use statistical metrics - Quantify distribution changes
- Cross-reference with governance - Correlate holdings with voting
The Token Holders API delivers unparalleled visibility into blockchain token distribution, enabling sophisticated analysis for developers, analysts, and researchers.