holdersCount

The holdersCount query returns the total number of unique wallet addresses holding assets from a specific contract or holding a specific token ID from a specific contract.

It returns a UInt64 scalar representing the aggregate count of distinct holders for the specified contract or token ID.

Schema Definition

holdersCount(
  contract: String!
  tokenId: UInt256
): UInt64!

Arguments

Argument	Type	Description
contract	String! non-null scalar	The contract address for which to count holders.
tokenId	UInt256 scalar	For ERC-1155 tokens, specify the token ID to count holders of a specific token.

Return Type

UInt64 scalar

Common Use Cases

• Display total holder metrics for ERC-20 token dashboards and analytics.
• Track NFT collection ownership distribution across unique wallets.
• Monitor holder growth over time for community engagement metrics.
• Build holder leaderboards by combining with holder balance queries.
• Analyze token concentration by comparing holder count to total supply.

Example

Query

Get Total Holders for an ERC-20 Token

query TokenHolderCount($contract: String!) {
  holdersCount(contract: $contract)
}

Variables

{
  "contract": "0xdac17f958d2ee523a2206206994597c13d831ec7"
}

Response

{
  "data": {
    "holdersCount": 4128387
  }
}

Implementation Notes

note

• For ERC-20 tokens, omit the tokenId parameter to get the total count of all unique holders.
• For ERC-721 tokens, the holder count without tokenId returns all unique owners across the entire collection. With tokenId, it typically returns 1 (or 0 if burned/unminted).
• For ERC-1155 tokens, specifying tokenId returns the count of wallets holding that specific token ID, as multiple wallets can hold the same ERC-1155 token.
• The count includes addresses with any non-zero balance, including those who may have received but not yet transferred tokens.
• Historical holder counts are not available through this query - it returns the current state only.
• For tracking holder changes over time, combine this query with timestamp-based snapshots in your application.