Top Token Holders by Contract Address

{
  "type": "object",
  "required": [
    "address",
    "chain"
  ],
  "properties": {
    "chain": {
      "enum": [
        "ethereum",
        "polygon",
        "bsc",
        "solana",
        "avalanche",
        "arbitrum",
        "optimism",
        "base"
      ],
      "type": "string",
      "description": "Chain. Can be ethereum, polygon, bsc, solana, avalanche, arbitrum, optimism, or base. Example: ethereum."
    },
    "limit": {
      "type": "integer",
      "default": 20,
      "maximum": 100,
      "minimum": 1,
      "description": "Results per page. Example: 20. Defaults to 20."
    },
    "offset": {
      "type": "integer",
      "default": 0,
      "maximum": 9007199254740991,
      "minimum": 0,
      "description": "Pagination offset. Example: 0. Defaults to 0."
    },
    "address": {
      "type": "string",
      "minLength": 1,
      "description": "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."
    },
    "include": {
      "type": "string",
      "minLength": 1,
      "description": "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."
    }
  },
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "address": {
            "type": "string",
            "description": "The holder's public onchain wallet address."
          },
          "balance": {
            "type": "string",
            "description": "Token balance as a decimal string (not a number), e.g. '3876420509.27412' -- kept as a string to avoid floating-point precision loss on large balances."
          },
          "percentage": {
            "type": "number",
            "description": "This holder's share of total token supply, as a percent (0-100)."
          },
          "entity_name": {
            "type": "string",
            "description": "A known exchange, protocol, or platform name the provider recognizes as owning this address (e.g. 'Binance', 'Coinbase', 'Sky (MakerDAO)'). Observed absent on some holders in the populated fixture (two entries had no entity_name/entity_type at all) -- not every holder address is labeled."
          },
          "entity_type": {
            "type": "string",
            "description": "Category for `entity_name`, e.g. 'cex' (centralized exchange), 'dex' (decentralized exchange), 'cdp' (collateralized debt / stablecoin protocol), or 'smart-contract-platform'. Only present alongside entity_name."
          }
        },
        "additionalProperties": false
      },
      "description": "One entry per holder, ranked by balance (largest first on the populated fixture). Genuinely empty (`[]`) when the provider has no indexed holder data for the address, as observed on a burn-address fixture -- this is a legitimate result, not an error."
    },
    "meta": {
      "type": "object",
      "properties": {
        "limit": {
          "type": "integer",
          "description": "Echoes the requested (or defaulted) limit."
        },
        "cached": {
          "type": "boolean",
          "description": "Whether this response was served from the provider's cache."
        },
        "offset": {
          "type": "integer",
          "description": "Echoes the requested (or defaulted) offset."
        },
        "has_more": {
          "type": "boolean",
          "description": "Whether more holders exist beyond this page."
        }
      },
      "additionalProperties": false
    }
  },
  "description": "The holder-list response, as returned at routing.responseResultPath ($.output).",
  "additionalProperties": false
}