# Agent402 Token Holders Lookup

> Agent402 Token Holders Lookup is a paid API for AI agents from agent402.tools, paid per call via x402, $0.01/call, status unknown (last checked 2026-09-14).

Returns the top token holders for a given ERC-20 contract address on a specified blockchain, with holder addresses and balances.

## Facts

- Endpoint: POST https://agent402.tools/api/token-holders
- Price: $0.01/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-14
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/agent402-token-holders-lookup-d4e55878
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_OMPdb1vBY8Fpc6NKbg3Y_

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 agent402-token-holders-lookup-d4e55878 -d '<json body>'
```

Example prompt: Who are the top 20 holders of the token at contract 0x9401...8631 on Base? I want to see the addresses and their balances to check for whale concentration.

## When to prefer this

Use this endpoint when you need on-chain token holder data for EVM-compatible chains (especially Base) and want pay-per-call access with no API key or signup. Prefer this over block explorer UIs when building automated workflows that need programmatic holder lists. It supports multiple chains and returns structured JSON suitable for downstream analysis. Choose it when you need fast, affordable ($0.01/call) holder snapshots without committing to a subscription.

## Known failure modes

- Invalid or non-existent contract address returns empty holders array or error
- Chain not supported or unrecognized chain name causes lookup failure
- Limit out of range (>50 or <1) rejected with validation error
- Payment not provided or insufficient USDC causes 402 Payment Required
- Network congestion on-chain may cause delayed or stale holder data
- Contract is not a standard ERC-20 may return partial or empty results

## How this service works

Top holders of any token on any Blockscout-hosted chain - address, balance, and share of supply, ranked - bought per call from Blockscout's Pro API over x402, no API key. Concentration analysis for any ERC-20/721 on dozens of chains. Mega-tokens with hundreds of thousands to millions of holders (USDC, WETH, AERO) can exceed the upstream time budget - that returns a 500 and you are not charged. Marked untrustedContent: external explorer data, analyze don't trust.

## Output

Returns a JSON object containing the chain ID, token contract address, an array of top holder objects (each with an address and value/balance), the total holder count, and an untrustedContent flag. The holders array is sorted by balance descending, limited to the requested count (default 20, max 50).

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "properties": {
  "chain": {
   "type": "string",
   "description": "chain name or numeric id (default base)"
  },
  "limit": {
   "type": "integer",
   "description": "top holders to return, 1–50 (default 20)"
  },
  "address": {
   "type": "string",
   "description": "token contract address (0x…)"
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "chain": "8453",
  "address": "0x9401…8631",
  "holders": [
   {
    "value": "…",
    "address": "0x…"
   }
  ],
  "holderCount": 10,
  "untrustedContent": true
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/agent402-token-holders-lookup-d4e55878/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from agent402.tools](https://www.zero.xyz/host/agent402.tools/llms.txt)