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

> How Webacy measures, classifies, and uses on-chain holder concentration data for stablecoins and RWA tokens to assess structural depeg and centralization risk.

On-chain concentration data for our stablecoin universe.

# What is it?

The **Holder Concentration Index (HCI)** measures how much of a token's circulating supply 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:

| Cohort     | What it captures                                                            |
| :--------- | :-------------------------------------------------------------------------- |
| **Top 10** | Share concentration among the 10 largest non-contract, non-exchange wallets |
| **Top 30** | Broader view of whale concentration (when available)                        |

Each cohort gives you three fields:

* **`index`** — a Herfindahl-style score (0–1): sum of squared fractional holdings. Higher = more concentrated.
* **`topSharePct`** — the linear percentage of supply held by those wallets (0–100). This is *not* `index × 100`; the two measure different things.
* **`riskBand`** — categorical classification based on threshold derivation (see below).

# Risk Bands

`riskBand` is derived from the Herfindahl `index` field:

| Band      | `index` range | Interpretation                                                             |
| :-------- | :------------ | :------------------------------------------------------------------------- |
| `low`     | \< 0.2        | Broadly distributed — whale exit unlikely to move the market               |
| `medium`  | 0.2 – 0.4     | Moderate concentration — worth watching for large transfers                |
| `high`    | 0.4 – 0.6     | Concentrated — a few exits could cause meaningful price impact             |
| `extreme` | ≥ 0.6         | Highly concentrated — single-whale sell events pose significant depeg risk |

You'll find the derivation thresholds in every API response as `meta.riskBandThresholds`, so you can verify classification without consulting external docs.

<Info>
  **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 single holder controls 60%+ of supply). The HCI surfaces latent structural risk that depeg price metrics miss until it materialises.
</Info>

# How HCI Affects the Risk Rating

HCI feeds directly into the **Structural risk component** (30% of the [Risk Rating](/safety-grade)). For non-fiat tokens, the Risk Rating uses `topSharePct` — the linear supply share — to apply risk adjustments:

| Condition             | `topSharePct` threshold         | Adjustment |
| :-------------------- | :------------------------------ | :--------- |
| Extreme concentration | top-10 holders ≥ 50% of supply  | +15 pts    |
| High concentration    | top-10 holders 30–50% of supply | +10 pts    |
| Medium concentration  | top-10 holders 10–30% of supply | +5 pts     |

<Info>
  HCI adjustments are **exempt for fiat\_reserve tokens** (USDC, USDT, etc.). Fiat-backed holders redeem at \$1 with the issuer — there is no exit-dump amplification risk. Crypto-collateral, delta-neutral, and algo tokens face real cascade risk from concentrated exits.
</Info>

Note the distinction: the API's `riskBand` is computed from the Herfindahl `index` (a non-linear concentration measure), while the Risk Rating adjustment uses `topSharePct` (a linear supply share). A token can sit in the `medium` Herfindahl band while still crossing the 30% `topSharePct` threshold that triggers a Risk Rating risk adjustment — and vice versa.

# Filters and Sorting

| Parameter           | Type         | Description                                                                              |
| :------------------ | :----------- | :--------------------------------------------------------------------------------------- |
| `chain`             | string       | Filter to a single chain (`eth`, `arb`, `base`, `opt`, `pol`, `bsc`, `sol`)              |
| `riskBand`          | enum         | Return only tokens in that band (`low` / `medium` / `high` / `extreme`). Case-sensitive. |
| `minTop10Index`     | number (0–1) | Minimum top-10 HCI index. E.g. `0.4` returns `high` and `extreme` tokens only.           |
| `sort`              | enum         | `top10Index` (default) · `top30Index` · `holderCount` · `symbol` · `chain`               |
| `order`             | enum         | `desc` (default) · `asc`                                                                 |
| `page` / `pageSize` | integer      | Default page size 50, max 500.                                                           |

### `byRiskBand` counts

`meta.byRiskBand` is always computed **before** the `riskBand` filter. This lets you display the full ecosystem breakdown (how many tokens are `extreme` right now?) even when you are viewing a filtered subset. `meta.totalUnfiltered` gives you the unfiltered record count for the same reason.

# Common Use Cases

| Goal                                         | Parameters                           |
| :------------------------------------------- | :----------------------------------- |
| Tokens with highest concentration risk       | `sort=top10Index&order=desc`         |
| Extreme-band tokens on Ethereum only         | `chain=eth&riskBand=extreme`         |
| Tokens with high+ top-10 concentration index | `minTop10Index=0.4`                  |
| Sort alphabetically for a token picker       | `sort=symbol&order=asc`              |
| Ecosystem risk snapshot (band distribution)  | Any request — read `meta.byRiskBand` |