> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moralis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Historical Token Holders

> Track changes in the holder base of an ERC20 token over time. Supports timeseries data for total holders as well as change metrics such as holder distribution and holder acquisition.

export const EndpointMeta = ({premium, cus, cusUnit, mainnetOnly}) => {
  const items = [];
  const planName = typeof premium === "string" ? premium : "Pro";
  if (premium) {
    items.push({
      icon: "\u26a0\ufe0f",
      label: "Premium endpoint",
      text: <>
          Requires the <strong>{planName} plan</strong> or above.{" "}
          <a href="/data-api/introduction/resources/premium-endpoints">
            View all
          </a>
          .
        </>
    });
  }
  if (cus) {
    const isDynamic = !!cusUnit;
    items.push({
      icon: "\u26a1",
      label: isDynamic ? "Dynamic cost" : "Endpoint cost",
      text: isDynamic ? <>
          {cus} CUs per {cusUnit}.{" "}
          <a href="/get-started/pricing#dynamic-endpoints">Learn more</a>.
        </> : <>
          {cus} CUs.{" "}
          <a href="/get-started/pricing">Learn more</a>.
        </>
    });
  }
  if (mainnetOnly) {
    items.push({
      icon: "\ud83d\udd17",
      label: "Mainnet only",
      text: <>Testnet chains are not supported.</>
    });
  }
  if (items.length === 0) return null;
  return <div className="endpoint-meta" style={{
    border: "1px solid var(--border-color, #e2e8f0)",
    borderRadius: "8px",
    overflow: "hidden",
    marginBottom: "16px",
    fontSize: "14px",
    lineHeight: "1.6",
    maxWidth: "100%"
  }}>
      <style dangerouslySetInnerHTML={{
    __html: `
            .endpoint-meta {
              --border-color: #e2e8f0;
              --row-bg: #f8fafc;
              --label-color: #0f172a;
              --text-color: #1f2937;
            }
            .endpoint-meta a {
              color: #0f7fff !important;
              text-decoration: underline;
            }
            @media (prefers-color-scheme: dark) {
              .endpoint-meta {
                --border-color: #374151 !important;
                --row-bg: #1e293b !important;
                --label-color: #f9fafb !important;
                --text-color: #e5e7eb !important;
              }
              .endpoint-meta a {
                color: #60a5fa !important;
              }
            }
            html.dark .endpoint-meta,
            [data-theme="dark"] .endpoint-meta {
              --border-color: #374151 !important;
              --row-bg: #1e293b !important;
              --label-color: #f9fafb !important;
              --text-color: #e5e7eb !important;
            }
            html.dark .endpoint-meta a,
            [data-theme="dark"] .endpoint-meta a {
              color: #60a5fa !important;
            }
          `
  }} />
      {items.map((item, i) => <div key={i} style={{
    display: "flex",
    alignItems: "baseline",
    gap: "8px",
    padding: "10px 14px",
    borderBottom: i < items.length - 1 ? "1px solid var(--border-color, #e2e8f0)" : "none",
    backgroundColor: "var(--row-bg, #f8fafc)"
  }}>
          <span style={{
    flexShrink: 0
  }}>{item.icon}</span>
          <span style={{
    wordBreak: "break-word",
    color: "var(--text-color, #1f2937)"
  }}>
            <strong style={{
    color: "var(--label-color, #0f172a)"
  }}>
              {item.label}:
            </strong>{" "}
            {item.text}
          </span>
        </div>)}
    </div>;
};

<EndpointMeta cus={50} />


## OpenAPI

````yaml /openapi-files/data-api/api.json GET /erc20/{tokenAddress}/holders/historical
openapi: 3.0.0
info:
  title: EVM API
  version: '2.2'
servers:
  - url: https://deep-index.moralis.io/api/v2.2
security:
  - ApiKeyAuth: []
tags: []
paths:
  /erc20/{tokenAddress}/holders/historical:
    get:
      tags:
        - Token
      summary: Get timeseries holders data
      description: >-
        Track changes in the holder base of an ERC20 token over time. Supports
        timeseries data for total holders as well as change metrics such as
        holder distribution and holder acquisition.
      operationId: getHistoricalTokenHolders
      parameters:
        - in: query
          name: chain
          description: The chain to query
          required: false
          schema:
            $ref: '#/components/schemas/chainList'
        - in: path
          name: tokenAddress
          description: The token address
          required: true
          schema:
            type: string
            example: '0x7d1afa7b718fb893db30a3abc0cfc608aacfebb0'
        - in: query
          name: fromDate
          description: >
            The starting date (format in seconds or datestring accepted by
            momentjs)
          required: true
          schema:
            type: string
            example: '2025-01-01T10:00:00'
        - in: query
          name: toDate
          description: >
            The ending date (format in seconds or datestring accepted by
            momentjs)
          required: true
          schema:
            type: string
            example: '2025-02-01T11:00:00'
        - in: query
          name: limit
          description: The number of results to return
          required: false
          schema:
            type: integer
            minimum: 0
        - in: query
          name: cursor
          description: >-
            The cursor returned in the previous response (used for getting the
            next page)
          required: false
          schema:
            type: string
        - in: query
          name: timeFrame
          description: The time frame to group the data by
          required: true
          schema:
            type: string
            example: 1d
            default: 1min
            enum:
              - 1min
              - 5min
              - 10min
              - 30min
              - 1h
              - 4h
              - 12h
              - 1d
              - 1w
              - 1m
      responses:
        '200':
          description: Returns token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenHolderTimelineResult'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    chainList:
      type: string
      example: eth
      default: eth
      enum:
        - eth
        - '0x1'
        - sepolia
        - '0xaa36a7'
        - polygon
        - '0x89'
        - bsc
        - '0x38'
        - bsc testnet
        - '0x61'
        - avalanche
        - '0xa86a'
        - cronos
        - '0x19'
        - arbitrum
        - '0xa4b1'
        - chiliz
        - '0x15b38'
        - gnosis
        - '0x64'
        - base
        - '0x2105'
        - base sepolia
        - '0x14a34'
        - optimism
        - '0xa'
        - polygon amoy
        - '0x13882'
        - linea
        - '0xe708'
        - moonbeam
        - '0x504'
        - moonriver
        - '0x505'
        - flow
        - '0x2eb'
        - flow-testnet
        - '0x221'
        - ronin
        - '0x7e4'
        - ronin-testnet
        - '0x31769'
        - lisk
        - '0x46f'
        - pulse
        - '0x171'
        - sei-testnet
        - '0x530'
        - sei
        - '0x531'
        - monad
        - '0x8f'
    TokenHolderTimelineResult:
      required:
        - result
      nullable: true
      properties:
        page:
          type: integer
          description: The current page of the result
          example: '1'
        pageSize:
          type: integer
          description: The number of results per page
          example: '100'
        cursor:
          type: string
          description: The cursor to get to the next page
        result:
          type: array
          items:
            $ref: '#/components/schemas/TokenHolderTimelineArray'
    TokenHolderTimelineArray:
      required:
        - timestamp
        - totalHolders
        - netHolderChange
        - holderPercentChange
        - holdersIn
        - holdersOut
        - newHoldersByAcquisition
      properties:
        timestamp:
          type: string
          description: Timestamp of the holder change ISO 8601 format
          example: '2021-05-07T11:08:35.000Z'
        totalHolders:
          type: integer
          description: The total holders of the token
          example: '100'
        netHolderChange:
          type: integer
          description: The net holder change
        holderPercentChange:
          type: integer
          description: The holder percentage change
        newHoldersByAcquisition:
          $ref: '#/components/schemas/TokenHolderSummaryHolderByAcquisition'
          type: object
          description: The new holders by acquisition
        holdersIn:
          $ref: '#/components/schemas/TokenHolderCategory'
          type: object
          description: The holders in by category
        holdersOut:
          $ref: '#/components/schemas/TokenHolderCategory'
          type: object
          description: The holders in by category
    TokenHolderSummaryHolderByAcquisition:
      required:
        - swap
        - transfer
        - airdrop
      properties:
        swap:
          type: number
          description: Number of wallets with first interaction as a swap
          example: '10'
        transfer:
          type: number
          description: Number of wallets with first interaction as a transfer
          example: '10'
        airdrop:
          type: number
          description: Number of wallets with first interaction as a airdrop
          example: '10'
    TokenHolderCategory:
      required:
        - whales
        - sharks
        - dolphins
        - fish
        - octopus
        - crabs
        - shrimps
      properties:
        whales:
          type: integer
          description: Number of wallets in the category
          example: '100'
        sharks:
          type: integer
          description: Number of wallets in the category
          example: '100'
        dolphins:
          type: integer
          description: Number of wallets in the category
          example: '100'
        fish:
          type: integer
          description: Number of wallets in the category
          example: '100'
        octopus:
          type: integer
          description: Number of wallets in the category
          example: '100'
        crabs:
          type: integer
          description: Number of wallets in the category
          example: '100'
        shrimps:
          type: integer
          description: Number of wallets in the category
          example: '100'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      x-default: test

````