> ## Documentation Index
> Fetch the complete documentation index at: https://docs.webacy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Holder Concentration Index API

> Query on-chain holder concentration metrics for stablecoins and RWA tokens, including risk bands, top-holder shares, and ecosystem-wide distributions.

## 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](/api-reference/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

<CardGroup cols={1}>
  <Card title="List Holder Concentration Index" icon="list" href="/api-reference/holder-concentration/list-holder-concentration-index">
    Paginated list of all tracked tokens with top-10 and top-30 concentration data, risk bands, and ecosystem-wide `byRiskBand` aggregates
  </Card>
</CardGroup>

***

## Key Concepts

### The Index vs. Top Share

Each cohort gives you two related but distinct numbers:

| Field | Formula | What it measures |
| - | - | - |
| `index` | organic top-N share − N ÷ holder count, floored at 0 | Excess concentration over an even spread (0–1) |
| `topSharePct` | organic top-N share × 100 | Percentage of supply those wallets hold |

"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` is near 0 and `topSharePct` reports the raw share.

`topSharePct = 80` means the top 10 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

| Band | `index` threshold | Signal |
| - | - | - |
| `low` | \< 0.2 | Broadly distributed |
| `medium` | 0.2 – 0.4 | Moderate concentration |
| `high` | 0.4 – 0.6 | Elevated — whale exits could move price |
| `extreme` | ≥ 0.6 | Highly concentrated — structural depeg risk |

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.

***

## Common Use Cases

| Use case | Parameters |
| - | - |
| Highest-risk tokens first | `sort=top10Index&order=desc` |
| Extreme-band tokens on Ethereum | `chain=eth&riskBand=extreme` |
| `high` and `extreme` top-10 bands only | `minTop10Index=0.4` |
| Alphabetical token picker | `sort=symbol&order=asc&pageSize=500` |
| Ecosystem risk snapshot | Any call — read `meta.byRiskBand` |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.