Token Holders

GET/gateway/v1/token/holders

Returns top token holders for a contract address.

Included fields: wallet address, balance, and percentage.

Lookup: by `address` and `chain`. Supports EVM chains and Solana.

Query Parameters

addressstringrequired

Token CONTRACT ADDRESS — 0x-prefixed hex for EVM chains, base58 for Solana. This is NOT a ticker symbol (e.g. do NOT pass `USDC` or `BTC`). To resolve a ticker symbol to a contract address, call GET /v1/search/token?q={symbol}&chain={chain} and use the `address` whose `chain` is supported by this endpoint. This endpoint has no `symbol` parameter.

Example: 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48

chainenum<string>required

Chain. Can be `ethereum`, `polygon`, `bsc`, `solana`, `avalanche`, `arbitrum`, `optimism`, or `base`.

Available options:ethereumpolygonbscsolanaavalanchearbitrumoptimismbase

Example: ethereum

limitinteger

Results per page

Example: 20

offsetinteger

Pagination offset

Example: 0

includestring

Comma-separated enrichments to attach to each holder. Currently valid: `labels` — adds a full `label` record alongside the flat `entity_name` / `entity_type` fields.

Example: labels

Token Holders

const options = {method: 'GET'};

fetch('https://api.asksurf.ai/gateway/v1/token/holders?address=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48&chain=ethereum&limit=20&offset=0&include=labels', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "$schema": "https://example.com/schemas/DataResponseTokenHolderItem.json",
  "data": [
    {
      "address": "<string>",
      "balance": "<string>",
      "entity_name": "<string>",
      "entity_type": "<string>",
      "label": {
        "address": "<string>",
        "entity_name": "<string>",
        "entity_type": "<string>",
        "labels": [
          {
            "confidence": 123,
            "label": "<string>"
          }
        ]
      },
      "percentage": 123
    }
  ],
  "meta": {
    "cached": true,
    "credits_used": 123,
    "empty_reason": "<string>",
    "has_more": true,
    "limit": 123,
    "offset": 123,
    "total": 123,
    "watermark": 123
  }
}