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

# Token Holder Metrics

> Returns total holders for a given token, as well as aggregated stats holder supply, holder trends, holder distribution and holder acquisition metrics.

export const MigrationCallout = ({guide}) => {
  if (!guide) return null;
  const href = `/data-feeds/migration/${guide}`;
  return <div className="migration-callout" style={{
    border: "1px solid var(--mc-border, #c7e9d6)",
    borderRadius: "8px",
    padding: "12px 14px",
    marginBottom: "16px",
    fontSize: "14px",
    lineHeight: "1.6",
    maxWidth: "100%",
    backgroundColor: "var(--mc-bg, #f0faf4)",
    display: "flex",
    alignItems: "baseline",
    gap: "8px"
  }}>
      <style dangerouslySetInnerHTML={{
    __html: `
            .migration-callout {
              --mc-border: #c7e9d6;
              --mc-bg: #f0faf4;
              --mc-text: #1f2937;
            }
            .migration-callout a {
              color: #0e7f4f !important;
              text-decoration: underline;
              font-weight: 600;
            }
            @media (prefers-color-scheme: dark) {
              .migration-callout {
                --mc-border: #1f5138 !important;
                --mc-bg: #102a1d !important;
                --mc-text: #e5e7eb !important;
              }
              .migration-callout a {
                color: #34d399 !important;
              }
            }
            html.dark .migration-callout,
            [data-theme="dark"] .migration-callout {
              --mc-border: #1f5138 !important;
              --mc-bg: #102a1d !important;
              --mc-text: #e5e7eb !important;
            }
            html.dark .migration-callout a,
            [data-theme="dark"] .migration-callout a {
              color: #34d399 !important;
            }
          `
  }} />
      <span style={{
    flexShrink: 0
  }}>{"📦"}</span>
      <span style={{
    color: "var(--mc-text, #1f2937)",
    wordBreak: "break-word"
  }}>
        <strong>Own this data instead.</strong> Move this endpoint onto your own
        infrastructure with <a href={href}>Data Feeds</a> — the same decoded
        onchain dataset, in real time, with no per-call limits.
      </span>
    </div>;
};

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} mainnetOnly />

<MigrationCallout guide="erc20-holders" />


## OpenAPI

````yaml openapi-files/data-api/api.json GET /erc20/{tokenAddress}/holders
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:
    get:
      tags:
        - Token
      summary: Get a holders summary by token address
      description: >-
        Returns total holders for a given token, as well as aggregated stats
        holder supply, holder trends, holder distribution and holder acquisition
        metrics.
      operationId: getTokenHolders
      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 to get transaction for
          required: true
          schema:
            type: string
            example: '0x6982508145454ce325ddbe47a25d4ec3d2311933'
      responses:
        '200':
          description: Returns token holder summary result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenHolderSummaryResult'
      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'
    TokenHolderSummaryResult:
      required:
        - totalHolders
        - holderSupply
        - holderChange
        - holdersByAcquisition
        - holderDistribution
      properties:
        totalHolders:
          type: number
          description: The total holders of the token
          example: '99999'
        holderSupply:
          $ref: '#/components/schemas/TokenHolderSummarySupply'
          type: object
          description: The holder supply
        holderChange:
          $ref: '#/components/schemas/TokenHolderSummaryHolderChange'
          type: object
          description: The holder change
        holdersByAcquisition:
          $ref: '#/components/schemas/TokenHolderSummaryHolderByAcquisition'
          type: object
          description: The holder change
        holderDistribution:
          $ref: '#/components/schemas/TokenHolderCategory'
          type: object
          description: The holder distribution
    TokenHolderSummarySupply:
      required:
        - top10
        - top25
        - top50
        - top100
        - top250
        - top500
      properties:
        top10:
          $ref: '#/components/schemas/TokenHolderSupplyChange'
          type: object
          description: The holder breakdown of the top 10 holders
        top25:
          $ref: '#/components/schemas/TokenHolderSupplyChange'
          type: object
          description: The holder breakdown of the top 25 holders
        top50:
          $ref: '#/components/schemas/TokenHolderSupplyChange'
          type: object
          description: The holder breakdown of the top 10 holders
        top100:
          $ref: '#/components/schemas/TokenHolderSupplyChange'
          type: object
          description: The holder breakdown of the top 10 holders
        top250:
          $ref: '#/components/schemas/TokenHolderSupplyChange'
          type: object
          description: The holder breakdown of the top 250 holders
        top500:
          $ref: '#/components/schemas/TokenHolderSupplyChange'
          type: object
          description: The holder breakdown of the top 500 holders
    TokenHolderSummaryHolderChange:
      required:
        - 5min
        - 1h
        - 6h
        - 24h
        - 7d
        - 3d
        - 30d
      properties:
        5min:
          $ref: '#/components/schemas/TokenHolderChange'
          type: object
          description: The holder change in the last 5 minutes
        1h:
          $ref: '#/components/schemas/TokenHolderChange'
          type: object
          description: Net holder change in the last 1 hour
        6h:
          $ref: '#/components/schemas/TokenHolderChange'
          type: object
          description: Net holder change in the last 6 hour
        24h:
          $ref: '#/components/schemas/TokenHolderChange'
          type: object
          description: Net holder change in the last 24 hour
        3d:
          $ref: '#/components/schemas/TokenHolderChange'
          type: object
          description: Net holder change in the last 3 days
        7d:
          $ref: '#/components/schemas/TokenHolderChange'
          type: object
          description: Net holder change in the last 7 days
        30d:
          $ref: '#/components/schemas/TokenHolderChange'
          type: object
          description: Net holder change in the last 30 days
    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'
    TokenHolderSupplyChange:
      required:
        - supply
        - supplyPercent
      properties:
        supply:
          type: string
          description: Net holder change
          example: '10'
        supplyPercent:
          type: number
          description: The percentage change
          example: '0.10'
    TokenHolderChange:
      required:
        - change
        - changePercent
      properties:
        change:
          type: number
          description: Net holder change
          example: '10'
        changePercent:
          type: number
          description: The percentage change
          example: '0.10'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      x-default: test

````