# x402helper.xyz ERC-20 Token Holder Rankings

> x402helper.xyz ERC-20 Token Holder Rankings is a paid API for AI agents from x402helper.xyz, paid per call via x402, $0.013/call, status unknown (last checked 2026-10-11).

Returns a ranked list of ERC-20 token holders on a specified blockchain chain, ordered by balance descending, with flags for first acquisition and transfer initiation.

## Facts

- Endpoint: GET https://x402helper.xyz/api/token/holders/:chainId/:address?utm_source=zero.xyz
- Price: $0.013/call
- Payment: x402
- Status: unknown
- Last checked: 2026-10-11
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/x402helper-xyz-erc-20-token-holder-rankings-cbf666e1
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_eI2pY6Iw8QyOhnzwaFfSQ

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 x402helper-xyz-erc-20-token-holder-rankings-cbf666e1
```

Example prompt: Show me the top ERC-20 token holders for the contract address 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 on Ethereum (chainId 1), ranked by balance — and flag which ones were first acquirers or transfer initiators.

## When to prefer this

Use this endpoint when you need on-chain holder rankings for a specific ERC-20 token on a particular chain, especially when you also want early-adopter signals (first-acquired and transfer-initiation flags). Prefer this over generic blockchain explorers when you need structured, programmatically consumable holder data with ranking already computed and enriched with behavioral flags.

## Known failure modes

- Invalid or non-existent contract address returns an error or empty list
- Unsupported chainId returns an error response
- Token contract with no holders returns an empty array
- Network/RPC issues for the specified chain may cause timeouts
- Rate limiting or payment verification failure due to x402 micropayment issues

## How this service works

ERC-20 token holders by chain - ranked by balance descending with first-acquired and transfer-initiation flags

## Output

A ranked list of wallet addresses holding the specified ERC-20 token on the given chain, sorted by balance from largest to smallest. Each entry includes the holder address, their token balance, and boolean flags indicating whether they were among the first to acquire the token and whether they initiated transfers.

## 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"
    },
    "pathParams": {
     "type": "object",
     "required": [
      "chainId",
      "address"
     ],
     "properties": {
      "address": {
       "type": "string",
       "description": "address path parameter"
      },
      "chainId": {
       "type": "string",
       "description": "chainId path parameter"
      }
     }
    },
    "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/x402helper-xyz-erc-20-token-holder-rankings-cbf666e1/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from x402helper.xyz](https://www.zero.xyz/host/x402helper.xyz/llms.txt)