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

> Ownership aggregates for a coin on a single network: total holders, top-100 share, wallet vs contract split, concentration by rank and holder tier distribution.<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 null metrics, not an error.
</Note>

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

<Tip>
  For the holder rows behind these aggregates use [/currencies/{id}/holders](https://docs.cryptorank.io/api-reference/currencies/token-holders).
</Tip>


## OpenAPI

````yaml /openapi.json get /v3/currencies/{id}/holders/summary
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/summary:
    get:
      tags:
        - Currencies
      summary: Token Holders Summary
      description: >-
        **Description**


        Ownership aggregates for a coin on a single network: total holders,
        top-100 share, wallet vs contract split, concentration by rank and
        holder tier distribution.


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


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


        > **Tip:** For the holder rows behind these aggregates use
        [/currencies/{id}/holders](https://docs.cryptorank.io/api-reference/currencies/token-holders).


        **Access**

        - Available from: **Advanced**

        - Cost: 1 credit per request
      operationId: CurrenciesController_getHoldersSummary
      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: >-
            Network to return aggregates 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
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/CurrencyHoldersSummaryDto'
                  status:
                    $ref: '#/components/schemas/ResponseStatusDto'
                required:
                  - data
                  - 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:
    CurrencyHoldersSummaryDto:
      properties:
        blockchainId:
          description: >-
            Network the aggregates are returned for. Null when the coin has no
            holders data.
          example: 1
          nullable: true
          type: number
        concentration:
          description: >-
            Supply concentration by holder rank bucket, fixed order from
            `top1_5` to `outside100`; `percentOfSupply` sums to 100. Empty when
            the coin has no holders data.
          items:
            $ref: '#/components/schemas/CurrencyHolderConcentrationBucketDto'
          type: array
        contractsShare:
          description: >-
            Share of the top-100 holdings owned by contracts, %. Sums to 100
            with `walletsShare`.
          example: 58.8
          nullable: true
          type: number
        holdersCount:
          description: >-
            Total number of holders on the network. Null when unavailable for
            the network.
          example: 4213567
          nullable: true
          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
        tierDistribution:
          description: >-
            Holder count by wallet size tier across the full holder base, all
            seven tiers in fixed order from `whale` to `shrimp`. Empty when
            unavailable for the network.
          items:
            $ref: '#/components/schemas/CurrencyHolderTierDto'
          type: array
        top100Share:
          description: Share of total supply held by the top 100 holders, %.
          example: 63.41
          nullable: true
          type: number
        totalSupply:
          description: Total token supply on the network.
          example: '73692183812.24'
          nullable: true
          type: string
        walletsShare:
          description: >-
            Share of the top-100 holdings owned by wallets, %. Sums to 100 with
            `contractsShare`.
          example: 41.2
          nullable: true
          type: number
      required:
        - blockchainId
        - snapshotDate
        - holdersCount
        - totalSupply
        - top100Share
        - walletsShare
        - contractsShare
        - concentration
        - tierDistribution
      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
    CurrencyHolderConcentrationBucketDto:
      properties:
        amount:
          description: Tokens held by the bucket.
          example: '12587457615.92'
          type: string
        bucket:
          description: >-
            Holder rank bucket. `outside100` is everything beyond the top 100
            holders.
          enum:
            - top1_5
            - top6_10
            - top11_25
            - top26_50
            - top51_100
            - outside100
          example: top1_5
          type: string
        percentOfSupply:
          description: >-
            Share of the token's total supply on this network held by the
            bucket, %.
          example: 17.08
          type: number
        value:
          description: Bucket value, USD. Null when the token has no USD price.
          example: '12591234567.12'
          nullable: true
          type: string
      required:
        - bucket
        - amount
        - percentOfSupply
        - value
      type: object
    CurrencyHolderTierDto:
      properties:
        holdersCount:
          description: Number of holders in the tier.
          example: 1200
          type: number
        holdersPercent:
          description: Share of all holders in the tier, %.
          example: 0.03
          type: number
        tier:
          description: Wallet size tier, from `whale` (largest) to `shrimp` (smallest).
          enum:
            - whale
            - shark
            - dolphin
            - fish
            - octopus
            - crab
            - shrimp
          example: whale
          type: string
      required:
        - tier
        - holdersCount
        - holdersPercent
      type: object
  securitySchemes:
    X-Api-Key:
      in: header
      name: X-Api-Key
      type: apiKey

````