# Arkham Token Holders by Address

> Arkham Token Holders by Address 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 token holders for a given token address on a specific chain, including entity labels, USD balances, and percentage of total supply held.

## Facts

- Endpoint: POST https://api.arkm.com/x402/token/holders/by-address
- 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-by-address-09dff8d2
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_CCnY_ujaXxHXtsr3MxDsJ

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-by-address-09dff8d2 -d '<json body>'
```

Example prompt: Who are the top holders of USDC on Ethereum? I want to see which wallets and entities hold the most, including their USD balances and what percentage of supply they control — use the Arkham token holders API with the USDC contract address 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48.

## When to prefer this

Use this endpoint when you need labeled, entity-enriched holder data for a specific token contract — especially when you want Arkham's proprietary entity tagging (identifying CEXes, protocols, DAOs, etc.) rather than raw on-chain data. Prefer this over generic blockchain explorers when institutional attribution and USD-denominated balances are important. Best for token concentration analysis, whale watching, and due diligence on token distribution.

## Known failure modes

- Invalid or unrecognized token contract address returns empty or error response
- Unsupported chain identifier causes request failure
- Insufficient USDC balance for the $6 x402 pay-per-request charge results in payment failure
- Token with no indexed holders returns empty holder arrays
- Rate limiting or API key issues may block access
- Newly deployed token contracts may have no holder data indexed yet

## How this service works

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

## Output

A JSON object containing token metadata (name, symbol, chain, contract address, pricing ID), total supply per chain, and ranked lists of top holder addresses with USD balance, percentage of market cap, contract status, Arkham wallet labels (name, chain type), and Arkham entity information (entity ID, name, type such as CEX or CDP, social/website links).

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "properties": {
  "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"
       },
       {
        "type": "boolean"
       }
      ]
     }
    }
   ],
   "description": "Optional Solana pool address. When provided, address holder unrealized PnL is calculated from this pool only."
  },
  "groupByEntity": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "number"
    },
    {
     "type": "boolean"
    },
    {
     "type": "array",
     "items": {
      "anyOf": [
      
… (truncated)
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "token": {
   "name": "USD Coin",
   "symbol": "USDC",
   "identifier": {
    "chain": "ethereum",
    "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "pricingID": "usd-coin"
   }
  },
  "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-by-address-09dff8d2/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)