# Wallet distribution statistics

Source: https://docs.settlemint.com/docs/api-reference/tokens/wallet-distribution-statistics
Read indexed holder concentration buckets for a token through the DALP API.



Use this endpoint to read how concentrated a token's holders are. It returns a fixed set of holder-count buckets sized against the largest single holder, plus the total number of holders with a positive balance. The data suits concentration charts, governance and risk reviews, and reporting. The endpoint reads indexed balances and does not move tokens or change token state.

## Endpoint [#endpoint]

```http
GET /api/v2/tokens/{tokenAddress}/stats/wallet-distribution
```

Set `tokenAddress` to the EVM contract address of the token in the active DALP tenant and system scope. The endpoint takes no query parameters.

## Smallest request [#smallest-request]

The following request fetches the holder distribution for one token. The response uses the single-resource envelope, where `buckets` is an ordered list from the smallest holdings to the largest:

```bash
curl "https://your-platform.example.com/api/v2/tokens/0x1111111111111111111111111111111111111111/stats/wallet-distribution" \
  -H "X-Api-Key: sm_dalp_xxxxxxxxxxxxxxxx"
```

```json
{
  "data": {
    "buckets": [
      { "range": "0-2%", "count": 128 },
      { "range": "2-10%", "count": 64 },
      { "range": "10-20%", "count": 12 },
      { "range": "20-40%", "count": 5 },
      { "range": "40-100%", "count": 2 }
    ],
    "totalHolders": 211
  },
  "links": {
    "self": "/v2/tokens/0x1111111111111111111111111111111111111111/stats/wallet-distribution"
  }
}
```

In this example, 211 wallets hold the token, and the two wallets in the `40-100%` bucket hold at least 40 percent of the largest single balance. A long tail in the `0-2%` bucket alongside a small top bucket points to a concentrated holder base.

## Parameters and fields [#parameters-and-fields]

| Field             | Location | Type        | Notes                                                                                           |
| ----------------- | -------- | ----------- | ----------------------------------------------------------------------------------------------- |
| `tokenAddress`    | Path     | EVM address | Token contract address. The address must be visible to the active DALP tenant and system scope. |
| `buckets`         | Body     | array       | Five holder-count buckets, ordered from the smallest holdings to the largest.                   |
| `buckets[].range` | Body     | string      | The bucket label as a share of the largest holder balance. See the bucket table below.          |
| `buckets[].count` | Body     | number      | Number of holders whose balance falls in this bucket.                                           |
| `totalHolders`    | Body     | number      | Total number of holders with a positive balance.                                                |

## How holders are bucketed [#how-holders-are-bucketed]

Each holder's balance is compared to the largest single holder balance for the token. The top holder sits at 100 percent, and every other wallet is placed in the bucket for its share of that maximum. The buckets describe concentration relative to the top holder, not each wallet's share of total supply.

| Bucket    | A holder lands here when its balance is                 |
| --------- | ------------------------------------------------------- |
| `0-2%`    | above 0 and below 2 percent of the largest balance      |
| `2-10%`   | at least 2 percent and below 10 percent                 |
| `10-20%`  | at least 10 percent and below 20 percent                |
| `20-40%`  | at least 20 percent and below 40 percent                |
| `40-100%` | at least 40 percent, up to and including the top holder |

The bucket boundaries are fixed, so the same response shape applies to every token. The bucket counts add up to `totalHolders`. Only holders with a positive balance are counted, so a wallet that has fully transferred out does not appear in any bucket.

A token with no indexed holders returns all five buckets with a `count` of 0 and a `totalHolders` of 0. Treat that as a token with no current holders or one whose balances have not been indexed yet, not as an error.

## CLI request [#cli-request]

The DALP CLI exposes the same read as `tokens stats-wallet-distribution`:

```bash
dalp tokens stats-wallet-distribution 0x1111111111111111111111111111111111111111
```

## How the value is calculated [#how-the-value-is-calculated]

DALP reads current indexed holder balances for the token, finds the largest holder balance, and counts how many holders fall in each share-of-maximum bucket. The total holder count is the number of holders with a balance above zero.

Because the endpoint reads indexed data, a recent transfer, mint, or burn can change holder balances before the relevant indexer has processed that change. If a just-completed balance change is not yet reflected, retry after indexing catches up before treating the difference as a reconciliation gap.

Concentration sized against the top holder answers a different question than supply share. A single dominant holder pins the 100 percent point, so most other holders can land in the lowest bucket even when their absolute balances differ. Read the buckets as a concentration profile relative to the largest position, and use the holders and transfers API when you need holder-level balances.

## Production handling [#production-handling]

* Authenticate the request with an API key that has access to the target tenant and system.
* Treat the response as indexed concentration data for one token, not a source for submitting or approving transfers.
* Read `buckets` as shares of the largest holder balance, not as shares of total supply.
* Expect the five fixed buckets in every response, including the all-zero shape for a token with no current holders.
* Use the [token holders and transfers API](/docs/api-reference/tokens/token-holders-transfers) when you need holder-level balances or the underlying transfer records.

## Related [#related]

* [Token holders and transfers](/docs/api-reference/tokens/token-holders-transfers)
* [Token supply statistics](/docs/api-reference/tokens/token-supply-statistics)
* [Token volume statistics](/docs/api-reference/tokens/token-volume-statistics)
* [Asset decimals](/docs/api-reference/reference/asset-decimals)