> ## 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

> This endpoint allows you to **query top token holders based on the provided token contract address on a network**

<Note>
  ### Note

  * The top holders data is currently in **Beta**, with ongoing improvements to data quality, coverage, and update frequency.
  * **Supported chains include**: Solana, EVM (Ethereum, Polygon, BNB, Arbitrum, Optimism, Base), Sui, TON, and Ronin.
  * Max `holders` value:
    * Maximum 50 for non-Solana networks, 40 for Solana network.
  * 💼 Exclusive for [Paid Plan](https://www.coingecko.com/en/api/pricing) subscribers (Analyst plan or above).
  * Cache / Update Frequency: every 60 seconds.
</Note>


## OpenAPI

````yaml api-reference/onchain-pro.json get /networks/{network}/tokens/{address}/top_holders
openapi: 3.0.0
info:
  title: Onchain DEX API (Pro)
  version: 3.0.0
servers:
  - url: https://pro-api.coingecko.com/api/v3/onchain
security:
  - apiKeyAuth: []
  - apiKeyQueryParam: []
paths:
  /networks/{network}/tokens/{address}/top_holders:
    get:
      tags:
        - Tokens
      summary: 💼 Top Token Holders by Token Address
      description: >-
        This endpoint allows you 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
          description: |-
            network ID 
             *refers to [/networks](/reference/networks-list)
          required: true
          schema:
            type: string
            example: base
            default: base
        - name: address
          in: path
          description: token contract address
          required: true
          schema:
            type: string
            example: '0x6921b130d297cc43754afba22e5eac0fbf8db75b'
            default: '0x6921b130d297cc43754afba22e5eac0fbf8db75b'
        - name: holders
          in: query
          description: >-
            number of top token holders to return, you may use any integer or
            `max` 
             Default value: 10
          required: false
          schema:
            type: string
            default: '1'
          examples:
            value-1:
              value: '1'
            value-2:
              value: max
        - name: include_pnl_details
          in: query
          required: false
          description: 'include PnL details for token holders, default: false'
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Get top token holders for a token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenHolder'
components:
  schemas:
    TokenHolder:
      type: object
      properties:
        data:
          type: object
          properties:
            id:
              type: string
            type:
              type: string
            attributes:
              type: object
              properties:
                last_updated_at:
                  type: string
                holders:
                  type: array
                  items:
                    type: object
                    properties:
                      rank:
                        type: number
                      address:
                        type: string
                      label:
                        type: string
                        nullable: true
                      amount:
                        type: string
                      percentage:
                        type: string
                      value:
                        type: string
                      average_buy_price_usd:
                        type: string
                      total_buy_count:
                        type: number
                      total_sell_count:
                        type: number
                      unrealized_pnl_usd:
                        type: string
                      unrealized_pnl_percentage:
                        type: string
                      realized_pnl_usd:
                        type: string
                      realized_pnl_percentage:
                        type: string
                      explorer_url:
                        type: string
      example:
        data:
          id: base_0x6921b130d297cc43754afba22e5eac0fbf8db75b
          type: top_holder
          attributes:
            last_updated_at: '2025-03-26T09:15:26.926Z'
            holders:
              - rank: 1
                address: '0x56bbe4200fdd412854bcf05f2c992827b64ee5c1'
                label: null
                amount: '9703812154.0'
                percentage: '14.3507'
                value: '1016009.26'
                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://basescan.org/address/0x56bbe4200fdd412854bcf05f2c992827b64ee5c1
              - rank: 2
                address: '0x5e498b4edf68820b859650e8d02d5ede3e6c260e'
                label: null
                amount: '9702318320.0'
                percentage: '14.3485'
                value: '1015852.85'
                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://basescan.org/address/0x5e498b4edf68820b859650e8d02d5ede3e6c260e
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-cg-pro-api-key
    apiKeyQueryParam:
      type: apiKey
      in: query
      name: x_cg_pro_api_key

````