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

> To get the historical token holders chart 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 <Callout icon="clock-rotate-left" color="#2196F3" iconType="regular">
        <strong>Cache / Update Frequency:</strong><br />{fmt(rate)}
      </Callout>;
  }
  if (publicRate !== undefined && paidRate !== undefined) {
    return <Callout icon="clock-rotate-left" color="#2196F3" iconType="regular">
        <strong>Cache / Update Frequency:</strong><ul><li>{fmt(paidRate)} (Paid API)</li><li>{fmt(publicRate)} (Demo / Keyless API)</li></ul>
      </Callout>;
  }
  return null;
};

export const PlanExclusivity = ({tier}) => {
  if (tier === "enterprise") {
    return <Callout icon="crown" color="#FFC107" iconType="regular">
        <strong>Enterprise Only</strong><br />This endpoint is exclusively available to <strong>Enterprise</strong> plan.<br /><a href="https://www.coingecko.com/en/api/enterprise">→ Contact sales</a>
      </Callout>;
  }
  if (tier === "analyst_above") {
    return <Callout icon="briefcase" color="#FFC107" iconType="regular">
        <strong>Analyst Plan and Above</strong><br />This endpoint is only available to <strong>Analyst, Lite, Pro, and Enterprise</strong> plan.<br /><a href="https://www.coingecko.com/en/api/pricing">→ View pricing</a>
      </Callout>;
  }
  if (tier === "basic_above") {
    return <Callout icon="briefcase" color="#FFC107" iconType="regular">
        <strong>Basic Plan and Above</strong><br />This endpoint is only available to <strong>Basic, Analyst, Lite, Pro, and Enterprise</strong> plan.<br /><a href="https://www.coingecko.com/en/api/pricing">→ View pricing</a>
      </Callout>;
  }
  throw new Error(`PlanExclusivity: invalid tier "${tier}". Use "basic_above", "analyst_above", or "enterprise".`);
};

#### Notes

* Historical token holders chart data is currently in **Beta**, with ongoing improvements to data quality, coverage, and update frequency.
* Auto-granularity via `days` param:
  * `7` = all data (no fixed intervals)
  * `30` = daily data (30 intervals)
  * `max` = weekly data

<Accordion title="Supported networks">
  | 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`   |
</Accordion>

<PlanExclusivity tier="analyst_above" />

<CacheInfo rate="60 seconds" />

#### SDK Examples

<CodeGroup>
  ```typescript TypeScript theme={null}
  const response = await client.onchain.networks.tokens.holdersChart.get('Dfh5DzRgSvvCFDoYc2ciTkMrbDfRKybA4SoFbPmApump', {
    network: 'solana',
  });

  console.log(JSON.stringify(response, null, 2));
  ```

  ```python Python theme={null}
  response = client.onchain.networks.tokens.holders_chart.get(
    "Dfh5DzRgSvvCFDoYc2ciTkMrbDfRKybA4SoFbPmApump",
    network="solana",
  )

  print(response.model_dump_json(indent=2))
  ```
</CodeGroup>


## OpenAPI

````yaml openapi-specs/pro-api.json get /onchain/networks/{network}/tokens/{token_address}/holders_chart
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/{token_address}/holders_chart:
    get:
      summary: Historical Token Holders Chart by Token Address
      description: >-
        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
          required: true
          description: >-
            Network ID. 

            *refers to [supported
            networks](/reference/token-holders-chart-token-address#supported-networks).
          schema:
            type: string
            default: solana
        - name: token_address
          in: path
          required: true
          description: Token contract address.
          schema:
            type: string
            default: Dfh5DzRgSvvCFDoYc2ciTkMrbDfRKybA4SoFbPmApump
        - name: days
          in: query
          required: false
          description: |-
            Number of days to return the historical token holders chart. 
            Default value: 7
          schema:
            type: string
            enum:
              - '7'
              - '30'
              - max
      responses:
        '200':
          description: Historical token holders chart data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenHoldersChart'
              example:
                data:
                  id: 1dc4b7d5-f0fc-431e-893b-91490652148e
                  type: token_holders_snapshot
                  attributes:
                    token_holders_list:
                      - - '2026-04-28T00:00:00.000Z'
                        - 52790
                      - - '2026-04-29T00:00:00.000Z'
                        - 52865
                meta:
                  token:
                    name: Pippin
                    symbol: pippin
                    coingecko_coin_id: pippin
                    address: Dfh5DzRgSvvCFDoYc2ciTkMrbDfRKybA4SoFbPmApump
components:
  schemas:
    TokenHoldersChart:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: object
          required:
            - id
            - type
            - attributes
          properties:
            id:
              type: string
              description: Request ID
            type:
              type: string
              description: Resource type
            attributes:
              type: object
              required:
                - token_holders_list
              properties:
                token_holders_list:
                  type: array
                  description: Historical token holders as [timestamp, holder_count] pairs
                  items:
                    type: array
                    items:
                      oneOf:
                        - type: string
                        - type: integer
        meta:
          type: object
          properties:
            token:
              type: object
              properties:
                name:
                  type: string
                  description: Token name
                symbol:
                  type: string
                  description: Token symbol
                coingecko_coin_id:
                  type: string
                  nullable: true
                  description: CoinGecko coin ID
                address:
                  type: string
                  description: Token contract 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)

````