Overview
Use the HCI API to retrieve paginated, daily-updated concentration data for our stablecoin universe. For each token you get how much of its supply is controlled by the top 10 and top 30 holders, classified into risk bands (low / medium / high / extreme).
Pair HCI with the Depeg Monitor to distinguish between tokens that are depegging right now and tokens with structural concentration risk that could trigger a depeg in the future.
Endpoints
List Holder Concentration Index
Paginated list of all tracked tokens with top-10 and top-30 concentration data, risk bands, and ecosystem-wide
byRiskBand aggregatesKey Concepts
The Index vs. Top Share
Each cohort gives you three related but distinct numbers, each with one fixed meaning:
“Organic” excludes exchange, bridge and pool wallets and every contract holder (staking vaults, lending markets, bridges). When every top-N holder is a protocol contract, the cohort carries
note: all_top_n_are_protocol_contracts_organic_low, index and topSharePct are 0 and rawTopSharePct shows the protocol-held share. Comparing the two shares tells you how much of the top-N sits in protocol inventory: crvUSD reads topSharePct ≈ 0.1 against rawTopSharePct ≈ 78.
source says where the numbers came from: holders (the fetched per-holder list, up to 50 holders) or aggregate (the data source’s top-N totals when the per-holder list could not support the cohort — topSharePct is then null and index is computed from the raw share). null on snapshots that predate the field. rawTopSharePct is null on snapshots produced before the pipeline published it, except older all-contracts cohorts (resolved to topSharePct 0) and older aggregate-sourced cohorts (resolved to topSharePct null), whose legacy share is published as rawTopSharePct.
top30 is null when the pipeline has no top-30 value; top30NullReason beside it says why: organic_cohort_not_larger_than_top10 (at most 10 of the 50 largest holders are organic, so a top-30 value would only repeat the top-10), fewer_than_30_holders_fetched, or no_top30_aggregate. A null top-30 is not a failure of the top-10.
topSharePct = 80 means the top 10 organic wallets hold 80% of supply. For a token with millions of holders the even-spread baseline is negligible, so index ≈ 0.8 too; for a token with 20 holders the top 10 would hold half the supply under an even spread, so index = 0.8 − 0.5 = 0.3.
Risk Bands
You’ll find the derivation thresholds in every response as
meta.riskBandThresholds.
byRiskBand is computed before the riskBand filter
meta.byRiskBand counts top-10 bands before the riskBand query filter, but after chain and minTop10Index. Without those two filters you get the full ecosystem distribution whatever riskBand you pass — useful for risk-breakdown dashboards without a separate unfiltered request.