# Blockscout Token Holders List

> Blockscout Token Holders List is a paid API for AI agents from api.blockscout.com, paid per call via x402, $0.002/call, status unknown (last checked 2026-09-15).

Returns a paginated list of addresses holding a specific token on a given blockchain, sorted by balance in descending order

## Facts

- Endpoint: GET https://api.blockscout.com/:chain_id/api/v2/tokens/:address_hash_param/holders
- Price: $0.002/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-15
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/blockscout-token-holders-list-92bf7854
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_-dLGmaFqJRV7BDINOhwjg

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 blockscout-token-holders-list-92bf7854
```

Example prompt: Can you pull the list of top token holders for the contract address 0x6B175474E89094C44Da98b954EedeAC495271d0F on Ethereum mainnet (chain ID 1) — I want to see who's holding the most DAI?

## When to prefer this

Use this endpoint when you need a ranked list of token holders for a specific ERC-20, ERC-721, or other token contract on a Blockscout-indexed chain. It is the right choice for whale analysis, token distribution studies, airdrop snapshots, governance participation checks, or any scenario where you need to enumerate who holds a token and in what quantity. Prefer it over generic block explorers when you need structured, machine-readable holder data via API rather than a web UI.

## Known failure modes

- Invalid or non-existent token contract address returns 404 or empty result set
- Unsupported or incorrect chain ID returns an error or no data
- Malformed address hash (wrong length, missing 0x prefix) returns a validation error
- Token exists but has no holders yet returns an empty list
- Rate limiting or quota exceeded returns a 429 error
- Pagination cursor is invalid or expired, returning an error

## How this service works

Access to api/v2/tokens/:address_hash/holders. List addresses holding a specific token sorted by balance

## Output

Returns a paginated list of wallet addresses holding the specified token, each entry including the holder's address and their token balance, sorted from largest to smallest balance. Also includes pagination metadata (next page cursor or total count) to allow full enumeration of all holders.

## 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",
      "HEAD",
      "DELETE"
     ],
     "type": "string"
    },
    "pathParams": {
     "type": "object",
     "properties": {
      "chain_id": {
       "type": "string"
      },
      "address_hash_param": {
       "type": "string"
      }
     }
    },
    "queryParams": {
     "type": "object",
     "properties": {
      "value": {
       "type": "string"
      },
      "items_count": {
       "type": "integer"
      },
      "address_hash": {
       "type": "string"
      }
     }
    }
   },
   "additionalProperties": false
  },
  "output": {
   "type": "object",
   "required": [
    "type"
   ],
   "properties": {
    "type": {
     "type": "string"
    },
    "example": {
     "type": "object"
    }
   }
  }
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/blockscout-token-holders-list-92bf7854/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from api.blockscout.com](https://www.zero.xyz/host/api.blockscout.com/llms.txt)