EVM Token Holders Cube

Token Holders

Token holder of a token refers to any wallet which holds that particular token. With Bitquery's TokenHolders API, you can get details related to the holders of any token.

{
  EVM(dataset: archive) {
    TokenHolders(
      tokenSmartContract: "0x514910771af9ca656af840dff83e8264ecf986ca"
      date: "2023-10-04"
      where: {
        Balance: { Amount: { gt: "0" } }
        BalanceUpdate: { FirstDate: { is: "2023-10-04" } }
      }
    ) {
      Balance {
        Amount
      }
      Holder {
        Address
      }
      Currency {
        Name
        Symbol
      }
    }
  }
}

Filter Parameters

Token Holder API allows you to narrow down your results using these parameters:

• date: Choose the date after which you want the token holders' data. It's required for all token holder queries.
• tokenSmartContract: Specify the token's address. It's required for all token holder queries.
• limit: Limit the results to a specified number of token holders.
• limitBy: Limit results based on a specific field's value.
• orderBy: Order results according to a field's value.
• where: Filter results based on specific criteria related to the value of the returned field.

Return Fields

The Token Holder API provides access to the following fields:

• Balance: Shows the token balance.
• BalanceUpdate: Offers a range of aggregated data related to balance updates, including:
  • FirstDate: The date of the holder’s first interaction with the token.
  • LastDate: The date of the holder’s most recent interaction with the token.
  • InAmount: The total amount of the token the holder received.
  • OutAmount: The total amount of the token the holder sent.
  • InCount: The number of transactions in which the holder received the token.
  • OutCount: The number of transactions in which the holder sent out the token.
• Currency: Provides currency-specific details, such as the smart contract and address.
• Holder: Retrieves the holder’s address.

Indexes and Factors

Indexes and factors are calculations that can be used to analyze data in the TokenHolders cube. They can be used to calculate a variety of metrics, such as the Gini coefficient, Nakamoto coefficient, and Thiel index.

Gini Factor

The Gini coefficient is a measure of inequality in a distribution. It is a number between 0 and 1, with 0 representing perfect equality and 1 representing perfect inequality. This query will calculate the Gini coefficient for the distribution of balances among all holders of the specified token.You can find the query here

query($currency: String! $date: String!) {
  EVM(dataset: archive) {
    TokenHolders(
      tokenSmartContract: $currency
      date: $date
      where: {
        Balance: {
          Amount: {
            gt: "0"
          }
        }
      }
    ) {
        gini(of: Balance_Amount)
    }
    }
}
{
  "currency": "0xdac17f958d2ee523a2206206994597c13d831ec7",
  "date": "2022-10-01"
}

Nakamoto Index

The Nakamoto coefficient is a measure of the centralization of a blockchain network. It is calculated by counting the number of holders that together control more than 51% of the total supply of a token an so the default value is 0.51.

It can be used to compare the decentralization of different blockchain networks. It can also be used to track the changes in decentralization of a blockchain network over time. The below query gives number of holders having 99% of the supply of USDT.You can find the query here

query($currency: String! $date: String!) {
  EVM(dataset: archive) {
    TokenHolders(
      tokenSmartContract: $currency
      date: $date
      where: {
        Balance: {
          Amount: {
            gt: "0"
          }
        }
      }
    ) {
        nakamoto(of: Balance_Amount ratio: 0.99)
    }
    }
}
{
  "currency": "0xdac17f958d2ee523a2206206994597c13d831ec7",
  "date": "2022-10-01"
}

Theil Index

The Thiel index is another measure of inequality in a distribution. It is calculated by taking the square of the sum of the market shares of all participants in a market. You can find the query here

query($currency: String! $date: String!) {
  EVM(dataset: archive) {
    TokenHolders(
      tokenSmartContract: $currency
      date: $date
      where: {
        Balance: {
          Amount: {
            gt: "0"
          }
        }
      }
    ) {
        theil_index(of: Balance_Amount)
    }
    }
}
{
  "currency": "0xdac17f958d2ee523a2206206994597c13d831ec7",
  "date": "2022-10-01"
}