# Heurist Mesh: ERC20 Top Token Holders

> Heurist Mesh: ERC20 Top Token Holders is a paid API for AI agents from mesh.heurist.xyz, paid per call via x402, $0.01/call, status unknown (last checked 2026-09-14).

Returns the top 50 token holders for a given ERC20/Solana token, including wallet addresses, balances, percentages held, and basic token metadata.

## Facts

- Endpoint: POST https://mesh.heurist.xyz/x402/solana/agents/EtherscanAgent/get_erc20_top_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/heurist-mesh-erc20-top-token-holders-5db4bac5
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_DmxxwiznvXkCU6us0KJNa

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 heurist-mesh-erc20-top-token-holders-5db4bac5 -d '<json body>'
```

Example prompt: Show me the top 50 holders of the USDC token contract — I want to see how concentrated the ownership is and which wallets hold the largest percentages of supply.

## When to prefer this

Use this endpoint when you need structured, ranked holder distribution data for a specific token — particularly when assessing whale concentration, insider holdings, or ownership decentralization. Prefer this over general blockchain explorers when you need the data in a machine-readable format ready for agent analysis. Best suited for ERC20 tokens indexed by Etherscan or Solana tokens supported by Heurist Mesh.

## Known failure modes

- Invalid or unrecognized token contract address returns an error or empty results
- Token not indexed by Etherscan/underlying data source returns no holder data
- Network mismatch (e.g. passing an Ethereum address for a Solana token) may yield incorrect results
- Rate limiting or upstream data provider unavailability returns a timeout or 402 payment error
- Very new tokens with minimal on-chain history may have incomplete holder data

## How this service works

Get top 50 token holders data including wallet addresses, balances, percentages, and basic token information. Use this tool to understand token holder distribution.

## Output

Returns a list of up to 50 token holder records, each containing the wallet address, token balance held, percentage of total supply, and holder rank. Also includes basic token metadata such as name, symbol, and total supply.

## 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",
    "bodyType",
    "body"
   ],
   "properties": {
    "body": {
     "type": "object",
     "required": [
      "chain",
      "address"
     ],
     "properties": {
      "chain": {
       "enum": [
        "ethereum",
        "base",
        "arbitrum",
        "zksync",
        "avalanche",
        "bsc"
       ],
       "type": "string",
       "description": "Blockchain network where the token is deployed"
      },
      "debug": {
       "type": "boolean",
       "default": false,
       "description": "Debug mode flag. ALWAYS use false."
      },
      "address": {
       "type": "string",
       "description": "Token contract address"
      }
     }
    },
    "type": {
     "type": "string",
     "const": "http"
    },
    "method": {
     "enum": [
      "POST"
     ],
     "type": "string"
    },
    "bodyType": {
     "enum": [
      "json"
     ],
     "type": "string"
    }
   },
   "additionalProperties": false
  },
  "output": {
   "type": "object",
   "required": [
    "type"
   ],
   "properties": {
    "type": {
     "type": "string"
    },
    "example": {
     "type": "object",
     "properties": {
      "result": {
       "type": "object",
       "additionalProperties": true
      }
     }
    }
   }
  }
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/heurist-mesh-erc20-top-token-holders-5db4bac5/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from mesh.heurist.xyz](https://www.zero.xyz/host/mesh.heurist.xyz/llms.txt)