# Token Holder Concentration Analysis

> Token Holder Concentration Analysis is a paid API for AI agents from api.chainmarket-api.workers.dev, paid per call via x402, $0.002/call, status unknown (last checked 2026-10-24).

Retrieves on-chain holder distribution metrics for an ERC-20 token on Ethereum mainnet, including top holder balances, share percentages, Gini coefficient, and concentration statistics.

## Facts

- Endpoint: GET https://api.chainmarket-api.workers.dev/api/crypto/token-holder-concentration?utm_source=zero.xyz
- Price: $0.002/call
- Payment: x402
- Status: unknown
- Last checked: 2026-10-24
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/token-holder-concentration-analysis-81a3d6c9
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_QI5_slT2_bv875dAfkYAk

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability token-holder-concentration-analysis-81a3d6c9
```

Example prompt: Can you pull the holder concentration data for the USDT token at contract address 0xdAC17F958D2ee523a2206206994597C13D831ec7 on Ethereum — I want to see the top holders, their share percentages, and the Gini coefficient to assess how centralized the supply is?

## When to prefer this

Choose this endpoint when you need on-chain, verifiable holder distribution data for an ERC-20 token on Ethereum mainnet — especially for whale concentration risk assessment, decentralization audits, or investment due diligence. It is preferable over generic portfolio or price APIs when the specific question is about ownership structure rather than price or liquidity. Best suited for DeFi research, token launch verification, or governance risk analysis where Gini coefficient and top-holder share percentages are required.

## Known failure modes

- Invalid or malformed contract address (not 0x + 40 hex chars) returns a 400 error
- Address is valid Ethereum format but not an ERC-20 token contract — may return empty or error response
- Token exists but has no holder data indexed on Blockscout — returns partial or empty holder list
- Payment fails due to unsupported network or insufficient USDC balance — call is not charged
- Upstream Blockscout API unavailability causes timeout or 502 error
- Token with very low holder count may produce statistically unreliable Gini coefficient

## How this service works

Ethereum ERC-20 holder concentration from Blockscout: top 100 holders' share of total supply, top 10 share, and a Gini coefficient over those 100 balances. Gini is over the top 100 only, not all holders. Ethereum mainnet only.

## Output

Returns a JSON object with the token's name, symbol, contract address, decimals, total supply, and total holder count. Includes a list of top holders (up to 100 sampled) with each holder's address, balance, and percentage share of supply. Also provides aggregate concentration metrics: top-10 share percentage, top-100 share percentage, and the Gini coefficient of the top holders, plus a timestamp of when the data was checked.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "required": [
  "input"
 ],
 "properties": {
  "input": {
   "type": "object",
   "required": [
    "type",
    "method"
   ],
   "properties": {
    "type": {
     "type": "string",
     "const": "http"
    },
    "method": {
     "enum": [
      "GET"
     ],
     "type": "string"
    },
    "queryParams": {
     "type": "object",
     "required": [
      "address"
     ],
     "properties": {
      "address": {
       "type": "string",
       "description": "ERC-20 token contract on Ethereum mainnet, 0x + 40 hex characters"
      }
     }
    }
   },
   "additionalProperties": false
  },
  "output": {
   "type": "object",
   "required": [
    "type"
   ],
   "properties": {
    "type": {
     "type": "string"
    },
    "example": {
     "type": "object"
    }
   }
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "name": "Tether",
  "source": "https://eth.blockscout.com/api/v2/tokens/0xdAC17F958D2ee523a2206206994597C13D831ec7/holders",
  "symbol": "USDT",
  "address": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
  "decimals": 6,
  "checkedAt": "2026-10-23T09:36:07.913Z",
  "topHolders": [
   {
    "address": "0xF977814e90dA44bFA03b6295A0616a897441aceC",
    "balance": 16000000001.13621,
    "sharePct": 18.1198
   },
   {
    "address": "0x47ac0Fb4F2D84898e4D9E7b4DaB3C24507a6D503",
    "balance": 9184997801.482302,
    "sharePct": 10.4019
   }
  ],
  "totalSupply": 88301265725.97054,
  "holdersTotal": 16915076,
  "top10SharePct": 48.5083,
  "giniTopHolders": 0.7672,
  "holdersSampled": 100,
  "top100SharePct": 66.2657
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/token-holder-concentration-analysis-81a3d6c9/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from api.chainmarket-api.workers.dev](https://www.zero.xyz/host/api.chainmarket-api.workers.dev/llms.txt)