---
title: "Top Token Holders by Token Address"
method: GET
path: "/onchain/networks/{network}/tokens/{address}/top_holders"
---

# Top Token Holders by Token Address

`GET /onchain/networks/{network}/tokens/{address}/top_holders`

To query top token holders based on the provided token contract address on a network

## Path parameters

- `network` string, required
- `address` string, required

## Query parameters

- `holders` string
- `include_pnl_details` boolean

## Response `200`

Top token holders data

- TopTokenHolders
  - `data` object, required
    - `id` string, required — Token identifier
    - `type` string, required — Resource type
    - `attributes` object, required
      - `last_updated_at` string, required — Data last updated timestamp
      - `holders` object[], required
        - `rank` integer, required — Holder rank
        - `address` string, required — Holder wallet address
        - `label` string, nullable, required — Address label
        - `amount` string, required — Token amount held
        - `percentage` string, required — Percentage of total supply held
        - `value` string, required — Value of holdings in USD
        - `average_buy_price_usd` string, nullable — Average buy price in USD
        - `total_buy_count` integer, nullable — Total number of buy transactions
        - `total_sell_count` integer, nullable — Total number of sell transactions
        - `unrealized_pnl_usd` string, nullable — Unrealized PnL in USD
        - `unrealized_pnl_percentage` string, nullable — Unrealized PnL percentage
        - `realized_pnl_usd` string, nullable — Realized PnL in USD
        - `realized_pnl_percentage` string, nullable — Realized PnL percentage
        - `explorer_url` string — Block explorer URL for the holder address

## Changes

- **2026-05-28** `11cc9e00fd86` — 2 breaking, 13 info
  - for the `query` request parameter `holders`, default value `1` was removed
  - for the `query` request parameter `include_pnl_details`, default value `false` was removed
  - api tag `Tokens` removed
  - the response property `data` became required for the status `200`
  - …11 more
- **2026-04-30** `fb6b6a203ce6` — 8 breaking
  - the response property `data/attributes/holders/items/average_buy_price_usd` became nullable for the status `200`
  - the response property `data/attributes/holders/items/label` became nullable for the status `200`
  - the response property `data/attributes/holders/items/realized_pnl_percentage` became nullable for the status `200`
  - the response property `data/attributes/holders/items/realized_pnl_usd` became nullable for the status `200`
  - …4 more
- **2026-02-25** `e88de4e81cdb` — 9 info
  - added the new optional `query` request parameter `include_pnl_details`
  - added the optional property `data/attributes/holders/items/average_buy_price_usd` to the response with the `200` status
  - added the optional property `data/attributes/holders/items/explorer_url` to the response with the `200` status
  - added the optional property `data/attributes/holders/items/realized_pnl_percentage` to the response with the `200` status
  - …5 more
- **2025-09-22** `91c83447321b` — 1 breaking
  - for the `query` request parameter `holders`, default value `1` was added

[Change history](https://skmtc.dev/coingecko/apis/coingecko-api/changes/onchain/networks/:network/tokens/:address/top_holders/get.md)

---

[API](https://skmtc.dev/coingecko/apis/coingecko-api.md) · [All operations](https://skmtc.dev/coingecko/apis/coingecko-api/llms.txt) · [OpenAPI document](https://skmtc.dev/coingecko/apis/coingecko-api/revisions/006c13c1a566?raw)