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

# Token Holders

> Top 100 token holders for a coin on a single network: address, label, type, balance, share of supply and USD value.<br/><br/>Available from&#58; <Badge color="green">Advanced</Badge><br/>Cost&#58; <Badge color="surface">1 credit per request</Badge>

<Note>
  Coverage is limited to the top-1000 coins by market cap and EVM networks only. Coins outside coverage return an empty array, not an error.
</Note>

<Note>
  Data is a daily snapshot; `meta.snapshotDate` returns its collection time. Holder metrics are per-network and are never summed across networks.
</Note>

<Tip>
  Resolve available networks for a coin via [/currencies/{id}/contracts](https://docs.cryptorank.io/api-reference/currencies/currency-contracts) and network ids via [/blockchains/map](https://docs.cryptorank.io/api-reference/blockchains/blockchain-map-id-reference).
</Tip>


## OpenAPI

````yaml /openapi.json get /v3/currencies/{id}/holders
openapi: 3.0.0
info:
  contact:
    email: info@cryptorank.io
    name: Cryptorank Team
    url: https://cryptorank.io
  description: >
    # Overview


    Cryptorank Public API v3 — comprehensive cryptocurrency data for B2B clients
    and partners.


    Useful Links:

    - [API Plans](https://cryptorank.io/public-api)

    - [Dashboard](https://cryptorank.io/public-api/dashboard)


    # Getting Started


    Primary Server URL:
    [https://api.cryptorank.io/v3/](https://api.cryptorank.io/v3/)


    **Authentication**


    Generate an API key in the
    [dashboard](https://cryptorank.io/public-api/dashboard) and pass it in the
    `X-Api-Key` header.


    Keep your keys secret — never commit them to public repositories or expose
    them in client-side code.
  title: Cryptorank API V3
  version: 3.0.0
servers:
  - url: https://api.cryptorank.io
security: []
tags: []
paths:
  /v3/currencies/{id}/holders:
    get:
      tags:
        - Currencies
      summary: Token Holders
      description: >-
        **Description**


        Top 100 token holders for a coin on a single network: address, label,
        type, balance, share of supply and USD value.


        > **Note:** Coverage is limited to the top-1000 coins by market cap and
        EVM networks only. Coins outside coverage return an empty array, not an
        error.


        > **Note:** Data is a daily snapshot; `meta.snapshotDate` returns its
        collection time. Holder metrics are per-network and are never summed
        across networks.


        > **Tip:** Resolve available networks for a coin via
        [/currencies/{id}/contracts](https://docs.cryptorank.io/api-reference/currencies/currency-contracts)
        and network ids via
        [/blockchains/map](https://docs.cryptorank.io/api-reference/blockchains/blockchain-map-id-reference).


        **Access**

        - Available from: **Advanced**

        - Cost: 1 credit per request
      operationId: CurrenciesController_getHolders
      parameters:
        - description: >-
            Coin ID. See: [GET
            /v3/currencies/map](https://docs.cryptorank.io/api-reference/currencies/currency-map-id-reference).
          in: path
          name: id
          required: true
          schema:
            example: 1
            type: integer
        - description: Page number (1-based). Returns up to 100 items per page.
          in: query
          name: page
          required: false
          schema:
            default: 1
            maximum: 1000
            minimum: 1
            type: number
        - description: >-
            Network to return holders for. Defaults to the coin's primary
            network — the one the website opens first. Unknown id → 400. See:
            [GET
            /v3/blockchains/map](https://docs.cryptorank.io/api-reference/blockchains/blockchain-map-id-reference).
          in: query
          name: blockchainId
          required: false
          schema:
            example: 1
            type: number
        - description: >-
            Exclude contract addresses from the list. `rank` and
            `percentOfSupply` keep their original values — they are not
            recalculated over the filtered set.
          in: query
          name: excludeContracts
          required: false
          schema:
            default: false
            type: boolean
        - description: >-
            Sort direction by `rank`. `desc` returns the same top holders
            starting from the lowest rank.
          in: query
          name: sortOrder
          required: false
          schema:
            default: asc
            enum:
              - asc
              - desc
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/CurrencyHolderItemDto'
                    type: array
                  meta:
                    $ref: '#/components/schemas/CurrencyHoldersMetaDto'
                  status:
                    $ref: '#/components/schemas/ResponseStatusDto'
                required:
                  - data
                  - meta
                  - status
                type: object
          description: ''
        '400':
          content:
            application/json:
              schema:
                properties:
                  error:
                    properties:
                      code:
                        enum:
                          - VALIDATION_ERROR
                        example: VALIDATION_ERROR
                        type: string
                      message:
                        example: Validation failed
                        type: string
                      status:
                        example: 400
                        type: number
                    required:
                      - code
                      - message
                      - status
                    type: object
                required:
                  - error
                type: object
          description: Request validation failed
        '401':
          content:
            application/json:
              schema:
                properties:
                  error:
                    properties:
                      code:
                        enum:
                          - API_KEY_MISSING
                          - API_KEY_INVALID
                        example: API_KEY_MISSING
                        type: string
                      message:
                        example: API key is missing
                        type: string
                      status:
                        example: 401
                        type: number
                    required:
                      - code
                      - message
                      - status
                    type: object
                required:
                  - error
                type: object
          description: API key is missing or invalid
        '403':
          content:
            application/json:
              schema:
                properties:
                  error:
                    properties:
                      code:
                        enum:
                          - NO_ACTIVE_SUBSCRIPTION
                          - ENDPOINT_NOT_AVAILABLE
                          - PLAN_LIMIT_EXCEEDED
                        example: NO_ACTIVE_SUBSCRIPTION
                        type: string
                      message:
                        example: No active subscription found
                        type: string
                      status:
                        example: 403
                        type: number
                    required:
                      - code
                      - message
                      - status
                    type: object
                required:
                  - error
                type: object
          description: >-
            No active subscription, the endpoint is not available in your plan,
            or the request goes beyond what your plan allows
        '404':
          content:
            application/json:
              schema:
                properties:
                  error:
                    properties:
                      code:
                        enum:
                          - NOT_FOUND
                        example: NOT_FOUND
                        type: string
                      message:
                        example: Resource not found
                        type: string
                      status:
                        example: 404
                        type: number
                    required:
                      - code
                      - message
                      - status
                    type: object
                required:
                  - error
                type: object
          description: Currency not found
        '429':
          content:
            application/json:
              schema:
                properties:
                  error:
                    properties:
                      code:
                        enum:
                          - RATE_LIMIT_EXCEEDED
                          - DAILY_CREDITS_EXCEEDED
                          - MONTHLY_CREDITS_EXCEEDED
                        example: RATE_LIMIT_EXCEEDED
                        type: string
                      message:
                        example: Rate limit exceeded
                        type: string
                      status:
                        example: 429
                        type: number
                    required:
                      - code
                      - message
                      - status
                    type: object
                required:
                  - error
                type: object
          description: Rate limit or credit limit exceeded
        '500':
          content:
            application/json:
              schema:
                properties:
                  error:
                    properties:
                      code:
                        enum:
                          - INTERNAL_ERROR
                        example: INTERNAL_ERROR
                        type: string
                      message:
                        example: Internal server error
                        type: string
                      status:
                        example: 500
                        type: number
                    required:
                      - code
                      - message
                      - status
                    type: object
                required:
                  - error
                type: object
          description: Internal server error
      security:
        - X-Api-Key: []
components:
  schemas:
    CurrencyHolderItemDto:
      properties:
        address:
          description: >-
            Holder address, full, lowercase as returned by the provider (not
            EIP-55 checksummed).
          example: '0xf977814e90da44bfa03b6295a0616a897441acec'
          type: string
        amount:
          description: Balance in tokens.
          example: '2517491523.184'
          type: string
        isContract:
          description: Whether the address is a contract.
          example: false
          type: boolean
        label:
          description: >-
            Known address label. Null when the address is unlabeled — the common
            case.
          example: Binance 8
          nullable: true
          type: string
        percentOfSupply:
          description: Share of the token's total supply on this network, %.
          example: 3.4162
          type: number
        rank:
          description: Holder position by balance, 1-based.
          example: 1
          type: number
        value:
          description: Balance value, USD. Null when the token has no USD price.
          example: '2518123456.12'
          nullable: true
          type: string
      required:
        - rank
        - address
        - label
        - isContract
        - amount
        - percentOfSupply
        - value
      type: object
    CurrencyHoldersMetaDto:
      properties:
        blockchainId:
          description: >-
            Network the holders are returned for. Null when the coin has no
            holders data.
          example: 1
          nullable: true
          type: number
        hasNextPage:
          description: Whether a further page of results exists
          example: true
          type: boolean
        page:
          description: Current page number (1-based)
          example: 1
          type: number
        pageSize:
          description: >-
            Fixed number of items per page for this endpoint (varies per
            endpoint)
          example: 25
          type: number
        snapshotDate:
          description: >-
            When the holders data was collected, ISO 8601 UTC. Null when the
            coin has no holders data.
          example: '2026-09-04T01:09:29.181Z'
          nullable: true
          type: string
      required:
        - page
        - pageSize
        - hasNextPage
        - blockchainId
        - snapshotDate
      type: object
    ResponseStatusDto:
      properties:
        timestamp:
          description: Server time of the response. Unix timestamp in milliseconds
          example: 1780000000000
          type: number
        usedCredits:
          description: Credits charged for this request
          example: 1
          type: number
      required:
        - usedCredits
        - timestamp
      type: object
  securitySchemes:
    X-Api-Key:
      in: header
      name: X-Api-Key
      type: apiKey

````