What is it?
The Holder Concentration Index (HCI) measures how much of a token’s supply (total supply, as the holder data source reports it) is held by a small group of wallets. When a handful of addresses control most of the supply, you face amplified depeg risk if those holders sell simultaneously. For each token, you get data across two cohorts:
Each cohort gives you these fields, each with one fixed meaning:
index— excess concentration (0–1): forsource: holders, the share of supply the top-N organic holders hold, minus the share they would hold if supply were spread evenly (N ÷ holder count), floored at 0; forsource: aggregate, the same calculation on the raw top-N share (no per-holder data, so contracts cannot be excluded). Organic means exchange, bridge and pool wallets and every contract holder (staking vaults, lending markets, bridges) are excluded. Nothing is subtracted when a token has N holders or fewer, so a single-holder token reads 1.topSharePct— the share of supply held by those organic top-N holders, in percent (0–100). Always the organic share;0when every top-N holder is a protocol contract,nullwhensourceisaggregate. For widely held tokens it reads close toindex × 100; the two differ when the even-spread baseline is material (tokens with few holders).rawTopSharePct— the share of supply held by the top-N holders with every holder counted (protocol contracts, exchanges and bridges included), in percent. Compare withtopSharePctto see how much of the top-N is protocol inventory: crvUSD reads ≈ 0.1% organic against ≈ 78% raw.nullon snapshots produced before the pipeline published it, except older cohorts whose legacy share was the raw one (see the note below).source—holderswhen the cohort was computed from the fetched per-holder list (up to 50 holders),aggregatewhen it fell back to the data source’s top-N totals (no per-holder data, sotopSharePctisnullandindexis computed from the raw share).nullon snapshots that predate the field.riskBand— categorical classification ofindex(see below).note— present when the cohort needs a caveat.all_top_n_are_protocol_contracts_organic_lowmeans every top-N holder is a protocol contract:indexandtopSharePctare 0 andrawTopSharePctcarries the protocol-held share.
top30 is null, holderConcentration.top30NullReason says why: organic_cohort_not_larger_than_top10 (at most 10 of the 50 largest holders are organic — the organic top-30 would be the same wallets as the organic top-10, and organic holders 11–30 sit below the fetched list), fewer_than_30_holders_fetched, or no_top30_aggregate.
Field meanings changed once. Before the pipeline published
rawTopSharePct, topSharePct carried the raw share whenever note was set or the cohort came from aggregate totals, so a token moving between cases (crvUSD, 78% → 0.1% on 2026-09-30) changed the field’s meaning under the same name. topSharePct is now always organic; the raw share lives in rawTopSharePct once the pipeline publishes it. The API resolves the older rows to the same contract — all-contracts cohorts to topSharePct 0, aggregate-sourced cohorts to topSharePct null, each with the legacy value in rawTopSharePct — on the list and on GET /rwa/hci/history alike, so the series reads with one meaning; other older points have rawTopSharePct / top10RawTopPct null.Risk Bands
riskBand is derived from the index field:
You’ll find the derivation thresholds in every API response as
meta.riskBandThresholds, so you can verify classification without consulting external docs.
HCI and depeg risk are complementary signals. A token can have a low Depeg Monitor score (price is stable today) but an
extreme HCI (a handful of holders control most of the supply). The HCI surfaces latent structural risk that depeg price metrics miss until it materializes.How HCI Affects the Risk Rating
HCI feeds directly into the Structural risk component of the Risk Rating. The Risk Rating reads the top-10index (hci_10) — the same number riskBand is derived from, and present on source: aggregate cohorts too — and deducts points from the structural score:
HCI deductions are exempt for the
fiat_reserve and rwa peg mechanisms: their holders redeem at par or NAV with the issuer, so there is no exit-dump amplification risk. The exception is RWA tokens curated as non-redeemable (private-credit, bond or lending-market positions), whose holders exit into the market — they keep the deduction. Crypto-collateral, delta-neutral and algorithmic tokens face real cascade risk from concentrated exits. A token with no HCI data (index missing) is not penalised — the Risk Rating record marks the gap (hci_data_missing) instead of scoring it.riskBand uses 0.2 / 0.4 / 0.6 on index, while the Risk Rating deduction uses 0.10 / 0.30 / 0.50 on the same index. A token can therefore sit in the low API band (index 0.15) and still carry a −5 structural deduction.
Filters and Sorting
byRiskBand counts
meta.byRiskBand counts top-10 bands before the riskBand filter, but after chain and minTop10Index. With no chain / minTop10Index, that’s the full ecosystem breakdown (how many tokens are extreme right now?) even while you view a filtered subset. meta.totalUnfiltered is the record count at the same point.