Token holders

There are a set of data sources dedicated to the token holder information of different tokens. All of them share the same data structure.

Let us use "WBTC Token Holders" as an example. At the end of every hour, we take a snapshot of the balances of the token holders who have sent or received any transactions within that hour. Here is what the data looks like:

Sample data

address: The wallet or smart contract address that has transacted the token.

balance: Token balance. The amount calculated here has already factored in the token decimals.

balanceUSD: The USD amount of the token balance at that time. So the token price used in the calculation is a historical value.

hour: The beginning of the hour when the snapshot was taken.

transfers: The array that contains all the transfer actions within the past hour. Each element of the array is a token "Transfer" event.

transfers.blockNumber: The block when the token "Transfer" event happened.

transfers.blockTimestamp: The corresponding time of the block

transfers.amount: The amount of token that was transferred. A positive value means tokens were transferred into the address while a negative value means the opposite.

transfers.amountUSD: The USD amount of the transferred tokens.

transfers.txHash: The unique hash of the transaction where the token "Transfer" happened.

latest (optional): The value will be true If the current record is the most recent one. Otherwise, this attribute won't show up. You can use this attribute when creating charts which require the latest balance or transaction of a certain wallet. For example: To display the top 20 token holders based on balance.

first (optional): The value will be true if the current record is the first time this wallet has ever sent or received a token. Otherwise, this attribute won't show up. You can use this attribute when creating charts which need to know whether it's the first time this wallet has transacted a token. For example: To display how many new wallets have started transacting the token.