# token-top-holders

> token-top-holders is a paid API for AI agents from chain.intel.rallylive.ca, paid per call via x402, $0.03/call, status unknown (last checked 2026-10-02).

Returns the top 50 holders of an ERC-20 token with supply share, balances, labels (contract/exchange), burned share, and concentration metrics across Base, Ethereum, Arbitrum, Optimism, Polygon, and BSC.

## Facts

- Endpoint: GET https://chain.intel.rallylive.ca/token/holders?utm_source=zero.xyz
- Price: $0.03/call
- Payment: x402
- Status: unknown
- Last checked: 2026-10-02
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/token-top-holders-958bbd07
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_BdAhaOYk_h705sOK7BejE

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-top-holders-958bbd07
```

Example prompt: Who are the top 50 holders of the token at 0x4ed4E862860beD51a9570b96d89aF5E1B0Efefed on Base? I want to see their supply share, any exchange or contract labels, and the concentration breakdown for the top 1, 5, 10, and 20 wallets.

## When to prefer this

Use this endpoint when you need to assess token holder concentration, whale risk, or insider control across EVM-compatible chains — especially Base, Ethereum, Arbitrum, Optimism, Polygon, or BSC. Prefer this over generic block explorers when you need structured, labeled, and pre-aggregated concentration metrics (top 1/5/10/20) in a single call rather than manually paginating holder lists. Best suited for pre-investment due diligence, DeFi risk screening, or automated token safety checks.

## Known failure modes

- Invalid or non-existent contract address returns an error or empty holder list
- Unsupported chain prefix causes a bad request or no data response
- Very new tokens with few on-chain transactions may have incomplete holder data
- Rate limits or payment failures (x402) may block the call
- Tokens on chains not supported by the endpoint return an error

## How this service works

Top 50 holders of a token with share of supply, balances, contract/exchange labels, burned share and concentration (top 1/5/10/20). Spot whale-controlled and insider-heavy tokens. Default chain Base; prefix another: ethereum:, arbitrum:, optimism:, polygon:, bsc:. $0.03 per call.

## Output

Returns a ranked list of the top 50 holder addresses for the token, each with their balance, share of total supply, and a contract/exchange label if applicable. Also includes the percentage of supply held by burned addresses, plus aggregated concentration metrics showing what fraction of supply the top 1, 5, 10, and 20 holders collectively own.

## 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",
     "properties": {}
    }
   },
   "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/token-top-holders-958bbd07/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from chain.intel.rallylive.ca](https://www.zero.xyz/host/chain.intel.rallylive.ca/llms.txt)