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

# 💼 Historical Token Holders Chart by Token Address

> This endpoint allows you to **get the historical token holders chart based on the provided token contract address on a network**

<Note>
  ### Note

  * The historical token holders chart 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.
  * `days` param provides the following automatic granularity:
    * `days=7` = **all data** (without fixed intervals)
    * `days=30` = **daily data** (30 daily intervals)
    * `days=max` = **weekly data**
  * 💼 Exclusive for Paid Plan subscribers (Analyst plan or above).
  * Cache / Update Frequency: every 60 seconds.
</Note>


## OpenAPI

````yaml api-reference/onchain-pro.json get /networks/{network}/tokens/{token_address}/holders_chart
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/{token_address}/holders_chart:
    get:
      tags:
        - Tokens
      summary: 💼 Historical Token Holders Chart by Token Address
      description: >-
        This endpoint allows you to **get the historical token holders chart
        based on the provided token contract address on a network**
      operationId: token-holders-chart-token-address
      parameters:
        - name: network
          in: path
          description: |-
            network ID 
             *refers to [/networks](/reference/networks-list)
          required: true
          schema:
            type: string
            example: eth
            default: eth
        - name: token_address
          in: path
          description: token contract address
          required: true
          schema:
            type: string
            example: '0xdac17f958d2ee523a2206206994597c13d831ec7'
            default: '0xdac17f958d2ee523a2206206994597c13d831ec7'
        - name: days
          in: query
          description: |-
            number of days to return the historical token holders chart 
             Default value: 7
          required: false
          schema:
            type: string
            enum:
              - '7'
              - '30'
              - max
      responses:
        '200':
          description: Get historical token holders chart for a token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenHolderChart'
components:
  schemas:
    TokenHolderChart:
      type: object
      properties:
        data:
          type: object
          properties:
            id:
              type: string
            type:
              type: string
            attributes:
              type: object
              properties:
                token_holders_list:
                  type: array
                  items:
                    type: array
                    items:
                      type: string
        meta:
          type: object
          properties:
            token:
              type: object
              properties:
                name:
                  type: string
                symbol:
                  type: string
                coingecko_coin_id:
                  type: string
                address:
                  type: string
      example:
        data:
          id: eb8f8786-9f4d-48f1-8124-eb2d9fd82b2d
          type: token_holders_snapshot
          attributes:
            token_holders_list:
              - - '2025-05-29T10:44:50.813Z'
                - 7705761
              - - '2025-05-29T11:45:03.137Z'
                - 7705748
        meta:
          token:
            address: '0xdac17f958d2ee523a2206206994597c13d831ec7'
            name: Tether USD
            symbol: USDT
            coingecko_coin_id: tether
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-cg-pro-api-key
    apiKeyQueryParam:
      type: apiKey
      in: query
      name: x_cg_pro_api_key

````