DALP API token wallet distribution statistics

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

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

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:

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

{
  "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

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

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

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

dalp tokens stats-wallet-distribution 0x1111111111111111111111111111111111111111

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

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 when you need holder-level balances or the underlying transfer records.

Wallet distribution statistics