> ## Documentation Index > Fetch the complete documentation index at: https://docs.coingecko.com/llms.txt > Use this file to discover all available pages before exploring further. # Top Token Holders by Token Address > To query top token holders based on the provided token contract address on a network export const CacheInfo = ({publicRate, paidRate, rate}) => { const fmt = v => v === 0 ? 'Real-time (Cacheless)' : `Every ${v}`; if (rate !== undefined) { return Cache / Update Frequency:
{fmt(rate)} ; } if (publicRate !== undefined && paidRate !== undefined) { return Cache / Update Frequency: ; } return null; }; export const PlanExclusivity = ({tier}) => { if (tier === "enterprise") { return Enterprise Only
This endpoint is exclusively available to Enterprise plan.
→ Contact sales ; } if (tier === "analyst_above") { return Analyst Plan and Above
This endpoint is only available to Analyst, Lite, Pro, and Enterprise plan.
→ View pricing ; } if (tier === "basic_above") { return Basic Plan and Above
This endpoint is only available to Basic, Analyst, Lite, Pro, and Enterprise plan.
→ View pricing ; } throw new Error(`PlanExclusivity: invalid tier "${tier}". Use "basic_above", "analyst_above", or "enterprise".`); }; #### Notes * Top holders data is currently in **Beta**, with ongoing improvements to data quality, coverage, and update frequency. * Max `holders` value: 50 for non-Solana networks, 40 for Solana. | Chain | Network `id` | | --------- | ------------- | | Solana | `solana` | | Ethereum | `eth` | | Base | `base` | | BNB Chain | `bsc` | | Optimism | `optimism` | | Arbitrum | `arbitrum` | | Polygon | `polygon_pos` | | TON | `ton` | | Sui | `sui-network` | | Robinhood | `robinhood` | | Ronin | `ronin` | | Bittensor | `bittensor` | #### SDK Examples ```typescript TypeScript theme={null} const response = await client.onchain.networks.tokens.topHolders.get('Dfh5DzRgSvvCFDoYc2ciTkMrbDfRKybA4SoFbPmApump', { network: 'solana', }); console.log(JSON.stringify(response, null, 2)); ``` ```python Python theme={null} response = client.onchain.networks.tokens.top_holders.get( "Dfh5DzRgSvvCFDoYc2ciTkMrbDfRKybA4SoFbPmApump", network="solana", ) print(response.model_dump_json(indent=2)) ``` ## OpenAPI ````yaml openapi-specs/pro-api.json get /onchain/networks/{network}/tokens/{address}/top_holders openapi: 3.0.0 info: title: CoinGecko Pro API version: 3.0.0 servers: - url: https://pro-api.coingecko.com/api/v3 security: - headerAuth: [] - queryAuth: [] paths: /onchain/networks/{network}/tokens/{address}/top_holders: get: summary: Top Token Holders by Token Address description: >- To query top token holders based on the provided token contract address on a network operationId: top-token-holders-token-address parameters: - name: network in: path required: true description: >- Network ID. *refers to [supported networks](/reference/top-token-holders-token-address#supported-networks). schema: type: string default: solana - name: address in: path required: true description: Token contract address. schema: type: string default: Dfh5DzRgSvvCFDoYc2ciTkMrbDfRKybA4SoFbPmApump - name: holders in: query required: false description: |- Number of top token holders to return, any integer or `max`. Default value: 10 schema: type: string - name: include_pnl_details in: query required: false description: |- Include PnL details for token holders. Default: `false` schema: type: boolean responses: '200': description: Top token holders data content: application/json: schema: $ref: '#/components/schemas/TopTokenHolders' example: data: id: solana_Dfh5DzRgSvvCFDoYc2ciTkMrbDfRKybA4SoFbPmApump type: top_holder attributes: last_updated_at: '2026-05-28T03:21:51.545Z' holders: - rank: 1 address: u6PJ8DtQuPFnfmwHbGFULQ4u4EgjDiyYKjVEsynXq2w label: Wallet 1 amount: '310021323.445634' percentage: '31.0041' value: '6157733.22' average_buy_price_usd: null total_buy_count: null total_sell_count: null unrealized_pnl_usd: null unrealized_pnl_percentage: null realized_pnl_usd: null realized_pnl_percentage: null explorer_url: >- https://solscan.io/account/u6PJ8DtQuPFnfmwHbGFULQ4u4EgjDiyYKjVEsynXq2w - rank: 2 address: 28RWPC6XPxSxUVjd27KiNRtcHVxKtd6cjms7eBcxiqdV label: null amount: '87536939.662678' percentage: '8.7543' value: '1738684.02' average_buy_price_usd: null total_buy_count: null total_sell_count: null unrealized_pnl_usd: null unrealized_pnl_percentage: null realized_pnl_usd: null realized_pnl_percentage: null explorer_url: >- https://solscan.io/account/28RWPC6XPxSxUVjd27KiNRtcHVxKtd6cjms7eBcxiqdV components: schemas: TopTokenHolders: type: object required: - data properties: data: type: object required: - id - type - attributes properties: id: type: string description: Token identifier type: type: string description: Resource type attributes: type: object required: - last_updated_at - holders properties: last_updated_at: type: string description: Data last updated timestamp holders: type: array items: type: object required: - rank - address - label - amount - percentage - value properties: rank: type: integer description: Holder rank address: type: string description: Holder wallet address label: type: string nullable: true description: Address label amount: type: string description: Token amount held percentage: type: string description: Percentage of total supply held value: type: string description: Value of holdings in USD average_buy_price_usd: type: string nullable: true description: Average buy price in USD total_buy_count: type: integer nullable: true description: Total number of buy transactions total_sell_count: type: integer nullable: true description: Total number of sell transactions unrealized_pnl_usd: type: string nullable: true description: Unrealized PnL in USD unrealized_pnl_percentage: type: string nullable: true description: Unrealized PnL percentage realized_pnl_usd: type: string nullable: true description: Realized PnL in USD realized_pnl_percentage: type: string nullable: true description: Realized PnL percentage explorer_url: type: string description: Block explorer URL for the holder address securitySchemes: headerAuth: type: apiKey in: header name: x-cg-pro-api-key description: >- Learn how to [set up your API key](https://docs.coingecko.com/docs/setting-up-your-api-key) queryAuth: type: apiKey in: query name: x_cg_pro_api_key description: >- Learn how to [set up your API key](https://docs.coingecko.com/docs/setting-up-your-api-key) ````