Measuring token holder concentration (Gini & HHI)

​

The use case

• How concentrated is this token? A handful of wallets controlling most of the supply is a governance and liquidity risk.
• Is it getting more or less concentrated over time? Concentration trending up after an unlock or an airdrop is a red flag.

• Gini coefficient: inequality across all holders. 0 means every holder owns an equal amount; 1 means a single wallet owns everything.
• HHI (Herfindahl-Hirschman Index): the sum of squared ownership shares. It ranges from 1/N (perfectly even across N holders) to 1 (one holder owns everything), and it is dominated by the largest holders, so it is the sharper “whale detector” of the two.

• the holder’s balance,
• the token’s total supply (to turn balances into ownership shares),
• the holder count (N),
• and, ideally, the ability to pull all of the above as of a past block so you can chart the trend.

​

The formulas

• HHI = Σ sᵢ²
• Gini = Σᵢ (2i − N − 1) · b₍ᵢ₎ / (N · Σ b₍ⱼ₎), where b₍ᵢ₎ are balances sorted ascending and i runs from 1 to N.

​

What you need from an API

​

Fetching holders and computing Gini & HHI with GoldRush

import { GoldRushClient } from "@covalenthq/client-sdk";

const client = new GoldRushClient("<GOLDRUSH_API_KEY>");

// Pull every holder. The SDK auto-paginates via the async iterator;
// page-size 1000 (the max) keeps the number of round-trips low.
async function getAllBalances(chain: string, token: string) {
  const balances: number[] = [];
  let totalSupply = 0;
  let decimals = 0;

  for await (const page of client.BalanceService.getTokenHoldersV2ForTokenAddress(
    chain,
    token,
    { pageSize: 1000 },
  )) {
    if (page.error) throw new Error(page.error_message);
    for (const holder of page.data.items ?? []) {
      decimals = holder.contract_decimals ?? 0;
      totalSupply = Number(holder.total_supply);          // returned inline
      balances.push(Number(holder.balance) / 10 ** decimals);
    }
  }
  return { balances, totalSupply: totalSupply / 10 ** decimals };
}

function hhi(values: number[]): number {
  const sum = values.reduce((a, b) => a + b, 0);
  if (sum === 0) return 0;
  return values.reduce((acc, v) => acc + (v / sum) ** 2, 0);
}

function gini(values: number[]): number {
  const xs = [...values].sort((a, b) => a - b);
  const n = xs.length;
  const sum = xs.reduce((a, b) => a + b, 0);
  if (n === 0 || sum === 0) return 0;
  let weighted = 0;
  for (let i = 0; i < n; i++) weighted += (2 * (i + 1) - n - 1) * xs[i];
  return weighted / (n * sum);
}

const { balances, totalSupply } = await getAllBalances(
  "eth-mainnet",
  "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", // USDC
);

// Optional: share of total supply held by the top 10 holders.
const top10 =
  [...balances].sort((a, b) => b - a).slice(0, 10).reduce((a, b) => a + b, 0) /
  totalSupply;

console.log({
  holders: balances.length,
  gini: gini(balances).toFixed(4),
  hhi: hhi(balances).toFixed(6),
  top10ShareOfSupply: (top10 * 100).toFixed(2) + "%",
});

​

The Etherscan approach

curl "https://api.etherscan.io/api?module=token&action=tokenholderlist\
&contractaddress=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48\
&page=1&offset=1000&apikey=<KEY>"

• fetch the total supply separately (the stats/tokensupply endpoint), since it is not in the holder response;
• apply the token’s decimals separately (also not in the holder response);
• accept that the list is current holders only, with no way to snapshot holders at a past block, so a concentration-over-time chart is not possible from this endpoint.

​

Side-by-side

​

Where GoldRush pulls ahead

1. One response has everything the math needs. balance, total_supply, and contract_decimals arrive together, so shares are a one-line calculation, with no second request and no separate supply/decimals bookkeeping.
2. Concentration over time, not just a snapshot. block-height and date let you recompute Gini/HHI at any historical point on Foundational Chains and chart the trend across unlocks, airdrops, and listings.
3. N comes for free. pagination.total_count gives the holder count in the same call, so the HHI floor (1/N) and Gini normalization need no extra request.
4. Fewer round-trips. A page size of 1000 plus SDK auto-pagination enumerates every holder with minimal code.
5. Same shape across 100+ chains. One API key and one code path cover Ethereum, Polygon, BSC, Base, Arbitrum, and more.

​

Where to start