# Arkham Token Holders

> Arkham Token Holders is a paid API for AI agents from api.arkm.com, paid per call via x402, $6/call, status unknown (last checked 2026-09-14).

Returns the top holders (by address and entity) for a given token, including USD balances, percentage of market cap, and Arkham entity labels.

## Facts

- Endpoint: POST https://api.arkm.com/x402/token/holders
- Price: $6/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-14
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/arkham-token-holders-1b879829
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_X06KGlfvS5IBmQqjUsFYy

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 arkham-token-holders-1b879829 -d '<json body>'
```

Example prompt: Using Arkham's intelligence data, show me the top holders of USDC on Ethereum — I want to see the wallet addresses, their USD balances, what percentage of supply they hold, and which entities like exchanges or protocols Arkham has attributed them to.

## When to prefer this

Choose this endpoint when you need on-chain token holder distribution data enriched with Arkham's proprietary entity attribution — particularly when you want to know not just which addresses hold a token, but which real-world entities (exchanges, protocols, funds) those addresses belong to. Prefer this over generic blockchain explorers when entity labeling and USD-denominated balances are important for the analysis.

## Known failure modes

- Invalid or unknown token symbol/identifier returns empty or error response
- Unsupported chain returns no holder data for that chain
- Payment failure via x402 results in 402 Payment Required with no data returned
- Rate limiting or quota exhaustion may result in 429 errors
- Token with no on-chain holder data returns empty holder arrays

## How this service works

Get Arkham top token holders by pricing ID or chain/address. $6.00 per call.

## Output

Returns a JSON object containing: token metadata (name, symbol, current price, 24h-ago price), total supply broken down by chain, top holders by address (with USD balance, percentage of market cap, Arkham wallet label, and full Arkham entity metadata including entity type, Twitter, website), and top holders by entity. Each address entry includes whether it is a contract or EOA.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "properties": {
  "id": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "number"
    },
    {
     "type": "boolean"
    },
    {
     "type": "array",
     "items": {
      "anyOf": [
       {
        "type": "string"
       },
       {
        "type": "number"
       },
       {
        "type": "boolean"
       }
      ]
     }
    }
   ],
   "description": "The CoinGecko pricing ID of the token."
  },
  "chain": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "number"
    },
    {
     "type": "boolean"
    },
    {
     "type": "array",
     "items": {
      "anyOf": [
       {
        "type": "string"
       },
       {
        "type": "number"
       },
       {
        "type": "boolean"
       }
      ]
     }
    }
   ],
   "description": "Blockchain network where the token is deployed."
  },
  "limit": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "number"
    },
    {
     "type": "boolean"
    },
    {
     "type": "array",
     "items": {
      "anyOf": [
       {
        "type": "string"
       },
       {
        "type": "number"
       },
       {
        "type": "boolean"
       }
      ]
     }
    }
   ],
   "description": "Maximum number of holders to return per page (default 100, max 100). offset + limit must not exceed 1000."
  },
  "offset": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "number"
    },
    {
     "type": "boolean"
    },
    {
     "type": "array",
     "items": {
      "anyOf": [
       {
        "type": "string"
       },
       {
        "type": "number"
       },
       {
        "type": "boolean"
       }
      ]
     }
    }
   ],
   "description": "Number of holders to skip for pagination (default 0)."
  },
  "address": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "number"
    },
    {
     "type": "boolean"
    },
    {
     "type": "array",
     "items": {
      "anyOf": [
       {
        "type": "string"
       },
       {
        "type": "number"
       },
       {
        "type": "boolean"
       }
      ]
     }
    }
   ],
   "description": "The token contract address to query."
  },
  "poolAddress": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "number"
    },
    {
     "type": "boolean"
    },
    {
     "type": "array",
     "items": {
      "anyOf": [
       {
        "type": "string"
       },
       {
        "type": "number"
       },

… (truncated)
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "token": {
   "name": "USDC",
   "price": 0.999831,
   "symbol": "usdc",
   "identifier": {
    "pricingID": "usd-coin"
   },
   "price24hAgo": 0.999825
  },
  "totalSupply": {
   "ethereum": 50539998661.70982
  },
  "entityTopHolders": {},
  "addressTopHolders": {
   "ethereum": [
    {
     "usd": 4453872464.461215,
     "address": {
      "chain": "ethereum",
      "address": "0x37305B1cD40574E4C5Ce33f8e8306Be057fD7341",
      "contract": false,
      "arkhamLabel": {
       "name": "LITE PSM USDC A POCKET",
       "address": "0x37305B1cD40574E4C5Ce33f8e8306Be057fD7341",
       "chainType": "evm"
      },
      "arkhamEntity": {
       "id": "makerdao",
       "name": "Sky (MakerDAO)",
       "note": "",
       "type": "cdp",
       "service": null,
       "twitter": "https://twitter.com/MakerDAO",
       "website": "https://makerdao.com",
       "linkedin": "https://www.linkedin.com/company/makerdao/",
       "crunchbase": "https://www.crunchbase.com/organization/makerdao"
      },
      "isUserAddress": false
     },
     "balance": 4453872464.461215,
     "pctOfCap": 0.06071662849686393
    },
    {
     "usd": 1699999999.039577,
     "address": {
      "chain": "ethereum",
      "address": "0xe1940f578743367F38D3f25c2D2d32D6636929B6",
      "contract": true,
      "arkhamLabel": {
       "name": "SingleOwnerMSCA (Proxy)",
       "address": "0xe1940f578743367F38D3f25c2D2d32D6636929B6",
       "chainType": "evm"
      },
      "arkhamEntity": {
       "id": "binance",
       "name": "Binance",
       "note": "",
       "type": "cex",
       "service": null,
       "twitter": "https://twitter.com/binance",
       "website": "https://binance.com",
       "linkedin": "https://www.linkedin.com/company/binance",
       "crunchbase": "https://www.crunchbase.com/organization/binance"
      },
      "isUserAddress": false
     },
     "balance": 1699999999.039577,
     "pctOfCap": 0.02317494926268423
    }
   ]
  }
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/arkham-token-holders-1b879829/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from api.arkm.com](https://www.zero.xyz/host/api.arkm.com/llms.txt)