# Blockscout Token Holders CSV Export

> Blockscout Token Holders CSV Export 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-10).

Exports a CSV file listing all addresses holding a specific token on a given blockchain, with optional period and filter parameters

## Facts

- Endpoint: GET https://api.blockscout.com/%7Bchain_id%7D/api/v2/tokens/%7Baddress_hash_param%7D/holders/csv
- Price: $0.002/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-10
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/blockscout-token-holders-csv-export-ea38a9bb
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_ASLEE3oulO2wKD47CGMe6

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-csv-export-ea38a9bb
```

Example prompt: Can you download the full CSV list of all holders for the USDC token at address 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 on Ethereum (chain ID 1) from Blockscout?

## When to prefer this

Use this endpoint when you need a bulk, downloadable export of all token holders in CSV format for offline analysis, airdrop distribution, or reporting — particularly when you need to process the data in spreadsheet tools or data pipelines. Prefer it over the paginated holders endpoint when you need the full list at once rather than page-by-page JSON results.

## Known failure modes

- Invalid chain_id returns 404 or empty response
- Invalid or non-existent token contract address returns error or empty CSV
- Unsupported filter_type value may return unfiltered results or error
- Very large holder sets may result in truncated CSV or timeout
- Malformed date strings in from_period/to_period may cause 400 bad request

## How this service works

Explore crypto activities with Blockscout's multichain search. Find transactions, addresses, tokens, and dapps across top blockchain networks — your go-to explorer for cross-chain blockchain data

## Output

A CSV file download containing a ranked list of token holder addresses along with their balances and share of total supply. The file includes columns for address, balance, and percentage held, and can be filtered by time period and custom filter criteria.

## 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": {
      "to_period": {
       "type": "string"
      },
      "filter_type": {
       "type": "string"
      },
      "from_period": {
       "type": "string"
      },
      "filter_value": {
       "type": "string"
      }
     }
    }
   },
   "additionalProperties": false
  }
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/blockscout-token-holders-csv-export-ea38a9bb/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)