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

# Token - Holder Distribution

> Retrieve distribution statistics for token holders based on their share of the total supply. Set include_list=true to return the wallet list for the specified range.

<Tabs>
  <Tab title="Usage Note">
    <p><strong>Two distribution modes. Pick one mode and only use filters for that mode.</strong></p>

    <ul>
      <li><code>mode=top</code> — returns the top holders by supply share. Use <code>top\_n</code> to control how many top holders to inspect.</li>
      <li><code>mode=percent</code> — returns holders inside a supply-share range. Use <code>min\_percent</code> and <code>max\_percent</code> to define the range.</li>
      <li><code>address\_type=wallet</code> returns holder wallets. <code>address\_type=token\_account</code> returns token-account level ownership.</li>
      <li><code>include\_list=true</code> returns the holder list. Set <code>include\_list=false</code> when you only need the summary.</li>
    </ul>

    <p><strong>Reading the numbers.</strong> <code>summary.wallet\_count</code> is the number of holders in the selected range. <code>summary.total\_holding</code> is the total token amount held by that segment, and <code>summary.percent\_of\_supply</code> is that segment's share of total supply.</p>
  </Tab>

  <Tab title="Accessibility">
    <ul>
      <li>Lite</li>
      <li>Starter</li>
      <li>Premium</li>
      <li>Business</li>
      <li>Enterprise</li>
    </ul>
  </Tab>

  <Tab title="Chain Supported">
    <p><strong>Solana</strong></p>
  </Tab>
</Tabs>

<Accordion title="Compute Unit ⚙️" icon="fa-gauge-high">
  <ul>
    <li>This endpoint consumes <code>30 CU</code> per request.</li>
  </ul>
</Accordion>

<Accordion title="Use Cases 💡" icon="fa-lightbulb">
  <ul>
    <li>Map the ownership shape of a token before trusting the market: see whether supply is spread across many wallets or concentrated in a few dominant hands.</li>
    <li>Build concentration-risk dashboards that flag tokens where the top holders control a dangerous share of supply.</li>
    <li>Segment holders by supply percentage to identify whales, mid-size holders, and long-tail retail distribution.</li>
    <li>Compare wallet-level and token-account-level views to understand whether apparent distribution is real or fragmented across accounts.</li>
    <li>Feed token safety scores, listing reviews, and pre-trade checks with holder concentration signals.</li>
  </ul>
</Accordion>

<Accordion title="How to Use 🛠️" icon="fa-book-open">
  <ul>
    <li>Provide a Solana <code>token\_address</code>.</li>
    <li>Use <code>mode=top\&top\_n=10</code> for the largest holders, or <code>mode=percent\&min\_percent=1\&max\_percent=5</code> for a supply-share bucket.</li>
    <li>Set <code>address\_type=wallet</code> for owner-level analysis, or <code>address\_type=token\_account</code> for token-account level inspection.</li>
    <li>Set <code>include\_list=false</code> for a lightweight summary, or keep it <code>true</code> when you need the actual holder rows.</li>
    <li>Use <code>offset</code> and <code>limit</code> to page through the holder list when <code>include\_list=true</code>.</li>
  </ul>
</Accordion>

<Accordion title="Best Practices ✅" icon="fa-check-circle">
  <ul>
    <li>Start with <code>mode=top</code> to identify concentration risk, then use <code>mode=percent</code> to inspect the middle and long-tail ownership bands.</li>
    <li>Do not mix top-holder filters with percent-range filters; each mode has its own filter set.</li>
    <li>Use wallet-level distribution for product and risk summaries, and token-account level distribution when investigating account fragmentation.</li>
    <li>Pair distribution with holder-profile, first-buyers, and token overview data to understand who owns supply and whether ownership looks healthy.</li>
  </ul>
</Accordion>

<Accordion title="Limitations ⚠️" icon="fa-exclamation-triangle">
  <ul>
    <li>Solana only.</li>
    <li><code>mode=top</code> cannot be combined with <code>min\_percent</code> or <code>max\_percent</code>.</li>
    <li><code>mode=percent</code> cannot be combined with <code>top\_n</code>.</li>
    <li><code>top\_n</code> supports up to 10,000 holders.</li>
    <li>Pagination supports offset up to 10,000 and limit up to 50.</li>
  </ul>
</Accordion>

<br />


## OpenAPI

````yaml openapi/data/openapi_docs.json GET /holder/v1/distribution
openapi: 3.1.0
info:
  version: 1.1.0
  title: Birdeye Data API
  description: >-
    Birdeye Data API is a full-spectrum blockchain and DEX data platform for
    teams that need production-grade crypto market intelligence across tokens,
    pairs, wallets, traders, protocols, and chains.


    From real-time prices, OHLCV, liquidity, and transaction flow to holder
    analytics, token and pair overviews, wallet portfolio and PnL, smart money,
    discovery, security, and blockchain-level utilities, Birdeye gives you a
    unified data layer for building serious crypto products at scale.


    Use it to power exchange interfaces, trading terminals, bots, market-making
    systems, quant research, alpha screeners, portfolio apps, wallet
    intelligence tools, alerting systems, analytics dashboards, and back-office
    data pipelines. Whether your users are retail traders, pro desks, analysts,
    or infrastructure teams, Birdeye helps you ship faster with broad market
    coverage and API surfaces that support both lightweight integrations and
    data-heavy workflows.


    To start, create an account at [bds.birdeye.so](https://bds.birdeye.so),
    generate an API key from the `Security` tab, and send it in the `X-API-KEY`
    header on every request.
servers:
  - url: https://public-api.birdeye.so
security:
  - apiKeyAuth: []
tags:
  - name: Price & OHLCV
  - name: Stats
  - name: Token/Market List
  - name: Transactions
  - name: Wallet, Networth & PnL
  - name: Balance & Transfer
  - name: Holder
  - name: Alltime & History
  - name: Blockchain
  - name: Account
  - name: Token
  - name: Transaction
  - name: Creation & Trending
  - name: Meme
  - name: Security
  - name: Search & Utils
  - name: Smart Money
  - name: Global Fees Paid
  - name: DEX & Protocol
  - name: Wallet Identity
paths:
  /holder/v1/distribution:
    get:
      tags:
        - Holder
      summary: Token - Holder Distribution
      description: >-
        Retrieve distribution statistics for token holders based on their share
        of the total supply. Set include_list=true to return the wallet list for
        the specified range.
      operationId: get-holder-v1-distribution
      parameters:
        - $ref: '#/components/parameters/xSolanaChainParam'
        - $ref: '#/components/parameters/tokenHolderDistributionTokenAddressParam'
        - $ref: '#/components/parameters/tokenHolderDistributionAddressTypeParam'
        - $ref: '#/components/parameters/tokenHolderDistributionModeParam'
        - $ref: '#/components/parameters/tokenHolderDistributionTopParam'
        - $ref: '#/components/parameters/tokenHolderDistributionMinPercentParam'
        - $ref: '#/components/parameters/tokenHolderDistributionMaxPercentParam'
        - $ref: '#/components/parameters/tokenHolderDistributionIncludeListParam'
        - $ref: '#/components/parameters/offset10kParam'
        - $ref: '#/components/parameters/limitParam'
      responses:
        '200':
          $ref: '#/components/responses/TokenHolderDistribution'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
components:
  parameters:
    xSolanaChainParam:
      name: x-chain
      description: Solana network only.
      in: header
      required: false
      schema:
        type: string
        enum:
          - solana
        default: solana
    tokenHolderDistributionTokenAddressParam:
      name: token_address
      description: Token contract address.
      in: query
      required: true
      schema:
        type: string
      examples:
        solana:
          value: 11111Zxp8hv4GVzZTWcgcFTcFCfPzW8YmbwvGahTBP
    tokenHolderDistributionAddressTypeParam:
      name: address_type
      description: Return holder distribution by wallet or token account address.
      in: query
      required: false
      schema:
        type: string
        default: wallet
        enum:
          - wallet
          - token_account
    tokenHolderDistributionModeParam:
      name: mode
      description: >-
        Holder filter mode (percent = by supply % range, top = top holders by
        supply %).
      in: query
      required: false
      schema:
        type: string
        default: top
        enum:
          - percent
          - top
    tokenHolderDistributionTopParam:
      name: top_n
      description: Number of top holders to return (used only when mode = top).
      in: query
      required: false
      schema:
        type: integer
        default: 10
        minimum: 1
        maximum: 10000
    tokenHolderDistributionMinPercentParam:
      name: min_percent
      description: >-
        Minimum % of total supply a holder must have (used only when mode =
        percent).
      in: query
      required: false
      schema:
        type: number
        minimum: 0
        maximum: 100
    tokenHolderDistributionMaxPercentParam:
      name: max_percent
      description: >-
        Maximum % of total supply a holder can have (used only when mode =
        percent).
      in: query
      required: false
      schema:
        type: number
        minimum: 0
        maximum: 100
    tokenHolderDistributionIncludeListParam:
      name: include_list
      description: Return holder list (true / false).
      in: query
      required: false
      schema:
        type: boolean
        default: true
    offset10kParam:
      name: offset
      description: Pagination start position. offset + limit <= 10000
      in: query
      required: false
      schema:
        type: integer
        default: 0
        minimum: 0
        maximum: 10000
    limitParam:
      name: limit
      description: Number of items per page.
      in: query
      required: false
      schema:
        type: integer
        default: 50
        minimum: 1
        maximum: 50
  responses:
    '400':
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            message: Bad request
    '401':
      description: Unauthorized. API key is missing or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            message: Unauthorized
    '403':
      description: Forbidden. Request is blacklisted or not whitelisted
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            message: Access Denied
    '429':
      description: Too Many Requests. Rate limit reached
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            message: Too many requests
    '500':
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            message: Internal Server Error
    TokenHolderDistribution:
      description: JSON object containing token holder distribution details
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TokenHolderDistributionResponse'
          examples:
            By wallet (default address_type=wallet):
              value:
                success: true
                data:
                  token_address: 11111Zxp8hv4GVzZTWcgcFTcFCfPzW8YmbwvGahTBP
                  mode: percent
                  summary:
                    wallet_count: 2
                    total_holding: '0.007374018405092705'
                    percent_of_supply: 0.0000017374018405092703
                  holders:
                    - wallet: aXG7W1eYYHN3SyAp515Dqu595wzNJxdGtcG5sjLVky1
                      holding: '0.000017910381239401126'
                      percent_of_supply: 0.0000017910381239401128
                    - wallet: aXG7W1wjjgiNnu8emgqJsTqbN86B8KEeKhN4J4JChqd
                      holding: '0.0000007910381239401126'
                      percent_of_supply: 0.0000017910381239401128
            By token account (address_type=token_account):
              value:
                success: true
                data:
                  token_address: 5nC81GfjADGGWTiTn2pSrzSefErvya1zUqKq1Ttio7N7
                  mode: percent
                  summary:
                    wallet_count: 2
                    total_holding: '292058.747997'
                    percent_of_supply: 100
                  holders:
                    - token_account: 7Sq3fyMWeE87pgi5G1E7HP3EuEHmkSDySpCQdZT9Bvc9
                      holding: '292057.747997'
                      percent_of_supply: 99.99966
                    - token_account: BG5hdVb1Ji3fSWMULxWxTsi3fRnddt6q31JWib1261ew
                      holding: '1'
                      percent_of_supply: 0.00034
  schemas:
    TokenHolderDistributionResponse:
      type: object
      description: >-
        Response containing holder-distribution summary data and optional holder
        rows.
      required:
        - success
        - data
      properties:
        success:
          type: boolean
          description: Whether the request succeeded.
        data:
          type: object
          description: Holder-distribution payload for the requested token and mode.
          required:
            - token_address
            - mode
            - summary
            - holders
          properties:
            token_address:
              type: string
              description: The token address the distribution was computed for.
            mode:
              type: string
              enum:
                - percent
                - top
              description: >-
                The filter mode the result was computed with. `percent` =
                holders within the [min_percent, max_percent] supply range,
                `top` = the top_n holders by supply share.
            summary:
              type: object
              description: >-
                Aggregated statistics across every holder matching the selected
                mode.
              properties:
                wallet_count:
                  type: integer
                  description: >-
                    Number of matching holders. Counts token accounts instead of
                    wallets when address_type=token_account.
                total_holding:
                  type: string
                  description: Total token amount held by all matching holders.
                percent_of_supply:
                  type: number
                  description: Percentage of total supply held by all matching holders.
            holders:
              type: array
              description: >-
                The matching holders, ordered by holding descending. Returned
                only when include_list=true; otherwise an empty array.
              items:
                type: object
                properties:
                  wallet:
                    type: string
                    description: >-
                      Holder wallet address. Returned when address_type=wallet
                      (default).
                  token_account:
                    type: string
                    description: >-
                      Holder token account address. Returned when
                      address_type=token_account.
                  holding:
                    type: string
                    description: Token amount held by this holder.
                  percent_of_supply:
                    type: number
                    description: Percentage of total supply held by this holder.
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      description: API key for authentication

````