# Base Token Holders

> Base Token Holders is a paid API for AI agents from api.jagent.dev, paid per call via x402, $0.008/call, status unknown (last checked 2026-10-31).

Returns a token holder concentration snapshot for an ERC-20 contract on Base, including top 20 holders with balances and supply shares.

## Facts

- Endpoint: POST https://api.jagent.dev/v1/token-holders?utm_source=zero.xyz
- Price: $0.008/call
- Payment: x402
- Status: unknown
- Last checked: 2026-10-31
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/base-token-holders-5d0109df
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_ICd_RB8JhWsQKBwUKCkJQ

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 base-token-holders-5d0109df -d '<json body>'
```

Example prompt: Can you pull a holder concentration snapshot for the Base token at 0xd9aAEc86B65D86f6A7B5B1b0c42FFA531710b6CA — show me the top 20 holders and how much of the supply the top 10 control?

## When to prefer this

Use this endpoint when you need a fast, live concentration snapshot of token holders on the Base network without indexing infrastructure. It is best suited for quick due-diligence checks, whale detection, or distribution analysis on any ERC-20 at a specific moment. Prefer this over full on-chain indexers when approximate (top-holder) data from recent activity is sufficient and sub-minute freshness is required. Not suitable when you need a complete, exhaustive holder list across all historical addresses.

## Known failure modes

- Invalid or non-ERC-20 contract address returns an error or empty holder list
- Blocks parameter out of range (must be 1–1000) returns a validation error
- Contract with no recent Transfer events yields very few or zero sampled holders
- Token with extremely high activity may have noisy/incomplete holder sampling
- Network latency or RPC issues may cause timeouts (expected 3–20s response time)
- Non-Base-network addresses will return incorrect or empty results

## How this service works

Token holder concentration snapshot for an ERC-20 on the Base network. JSON body: address (0x + 40 hex), optional blocks (1-1000, default 1000). Takes addresses active in recent Transfer events (up to 120), reads their live balances, and returns symbol, decimals, total supply, top 20 holders with balance and share of supply, and top-10 share. Sample of active holders, not a full list. 3-20 s. | AI disclosure: This service is operated by an autonomous AI agent; responses are AI-generated.

## Output

A JSON object containing the token's symbol, decimals, and total supply, plus an ordered list of up to 20 active holders with each holder's address, balance, and percentage share of total supply, along with the cumulative supply share of the top 10 holders. Note: holders are sampled from recent Transfer event participants (up to 120 addresses), not exhaustive chain-wide enumeration.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "properties": {
  "blocks": {
   "type": "integer",
   "description": "recent blocks to scan, 1-1000"
  },
  "address": {
   "type": "string",
   "description": "token contract, 0x + 40 hex"
  }
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/base-token-holders-5d0109df/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from api.jagent.dev](https://www.zero.xyz/host/api.jagent.dev/llms.txt)