# Arkham Token Holders by ID

> Arkham Token Holders by ID 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 specific token, including balances, USD values, percentage of market cap, and Arkham intelligence labels.

## Facts

- Endpoint: POST https://api.arkm.com/x402/token/holders/by-id
- 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-id-89cb985a
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_g7uIHb9EQzf4ovWgNif9r

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-id-89cb985a -d '<json body>'
```

Example prompt: Using Arkham's intelligence data, show me the top wallet holders of USDC (pricing ID: usd-coin) on Ethereum — I want to see their balances, USD values, percentage of supply, and which entities like exchanges or protocols own them.

## When to prefer this

Use this endpoint when you need Arkham's proprietary entity-labeled on-chain holder data for a specific token — particularly when you want to distinguish between anonymous wallets and known entities (exchanges, DAOs, protocols). Prefer this over generic on-chain RPC queries when you need human-readable labels, USD valuations, and institutional attribution. Best for whale tracking, concentration analysis, and institutional ownership research.

## Known failure modes

- Invalid or unknown token pricing ID returns empty or error response
- Unsupported chain in query returns no holder data
- Malformed POST body causes 400 Bad Request
- Insufficient x402 payment or expired payment token causes 402 Payment Required
- Rate limiting or quota exceeded returns 429 Too Many Requests
- Token with no tracked holders returns empty addressTopHolders and entityTopHolders arrays

## How this service works

Get Arkham top token holders by pricing ID. $6.00 per call.

## Output

A JSON object containing: token metadata (name, symbol, current price, 24h ago price), total supply per chain, top holders broken down by entity and by address. Each address entry includes the wallet address, chain, balance, USD value, percentage of market cap, Arkham label (human-readable name), and Arkham entity details (entity ID, name, type such as CEX/CDP, website, Twitter, LinkedIn, Crunchbase).

## 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."
  },
  "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)."
  },
  "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": [
       {
        "type": "string"
       },
       {
        "type": "number"
       },
       {
        "type": "boolean"
       }
      ]
     }
    }
   ],
   "description": "If 'true', groups holdings by entity rather than individual addresses."
  }
 }
}
```

## 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-by-id-89cb985a/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)