ERC-20 holder-distribution analytics: Gini, concentration curve, whale tiers API

Deep holder-distribution analytics for an ERC-20 token (distribution science, NOT a risk verdict). From the real top-holder list it computes the holder count, the top-1/top-5/top-10/top-50 concentration curve, a Gini coefficient over the sampled holders (0 = perfectly equal, 1 = one wallet holds everything), whale-tier counts (holders >1% and >0.1% of supply), and a distribution-shape verdict (highly_concentrated | moderate | well_distributed). It also returns a circulating-holder view that excludes detectable burn, LP, and known contract addresses (via a curated label set plus the explorer is_contract flag) so the metrics reflect real end-holders rather than the null address or a DEX pool. Answers 'How concentrated is this token's supply?', 'What is the Gini coefficient of the holders?', 'How many whales hold more than 1% of supply?', 'Is this token well distributed or whale-dominated?'.

Price$0.16per request

MethodPOST

Route/v1/chain/token-holder-analytics

StatusLive

MIME typeapplication/json

Rate limit60/minute

Cache900s public

chaintokenholdersdistributionconcentrationginiwhaleserc20analyticsdecentralization

API URLhttps://x402.hexl.dev/v1/chain/token-holder-analytics

Integration docs

Example request

{
  "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
  "chain": "ethereum"
}

Example response

{
  "token": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
  "chain": "ethereum",
  "symbol": "USDC",
  "name": "USDC",
  "totalSupply": "51914128593723110",
  "decimals": 6,
  "holdersCount": 7593526,
  "holdersSampled": 50,
  "concentration": {
    "top1": 0.0834,
    "top5": 0.2101,
    "top10": 0.2849,
    "top50": 0.475
  },
  "gini": 0.5289,
  "whaleTiers": {
    "over1Pct": 10,
    "over0_1Pct": 50
  },
  "distributionShape": "moderate",
  "circulating": {
    "holdersSampled": 35,
    "excludedSupplyShare": 0.2109,
    "top1": 0.0834,
    "gini": 0.4871,
    "excluded": [
      {
        "address": "0x000000000000000000000000000000000000dead",
        "reason": "burn",
        "label": "Dead Address (burn)"
      },
      {
        "address": "0x40ec5b33f54e0e8a33a975908c5ba1c14e5bbbdf",
        "reason": "contract",
        "label": "Polygon ERC20 Bridge"
      }
    ]
  },
  "narrative": "MODERATELY distributed across the sampled top 50 holders. 7,593,526 total holders; top-1 8.3%, top-10 28.5%, top-50 47.5% of supply. Gini 0.5289. 10 sampled holder(s) hold >1% and 50 hold >0.1% of supply. Excluded 15 non-end-holder address(es) (burn/LP/contract = 21.1% of supply) from the circulating view. Distribution analytics only — NOT a risk or safety verdict.",
  "methodologyVersion": "token-holder-analytics-2026.1",
  "disclaimer": "Holder-distribution analytics from public explorer data and a bounded top-50 holder sample; Gini and whale-tier counts are computed over that sample, not the full holder base. Burn/LP/contract exclusion is best-effort. This is distribution ANALYTICS, NOT a risk, safety, or investment verdict. Verify before relying on it."
}

Input schema

{
  "type": "object",
  "required": [
    "address"
  ],
  "properties": {
    "address": {
      "type": "string",
      "description": "0x-prefixed 40-hex ERC-20 token contract address."
    },
    "chain": {
      "type": "string",
      "enum": [
        "base",
        "ethereum"
      ],
      "default": "ethereum",
      "description": "Chain the token is deployed on."
    }
  },
  "examples": [
    {
      "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "chain": "ethereum"
    }
  ]
}

Output schema

{
  "type": "object",
  "additionalProperties": true
}