> ## 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

> 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`       | Σ (share²) for top-N holders      | Herfindahl concentration — weights large holders more heavily |
| `topSharePct` | Σ (share) for top-N holders × 100 | Linear percentage of supply those wallets hold                |

`topSharePct = 80` means the top 10 wallets hold 80% of supply.\
`index = 0.8` would mean the supply is *extremely* concentrated even within that group — e.g. one wallet holding almost everything. Together, both fields give you the full picture.

### 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 pre-filter

`meta.byRiskBand` counts are computed **before** the `riskBand` query filter is applied. This means you always get the full ecosystem distribution regardless of what filter you have active — useful for building risk-breakdown dashboards without making 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`         |
| Tokens above 40% concentration threshold | `minTop10Index=0.4`                  |
| Alphabetical token picker                | `sort=symbol&order=asc&pageSize=500` |
| Ecosystem risk snapshot                  | Any call — read `meta.byRiskBand`    |