---
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`

## Request

- Base URL: `https://api.coingecko.com/api/v3`
- URL: `https://api.coingecko.com/api/v3/onchain/networks/{network}/tokens/{address}/top_holders`
- Auth: one of:
  - API key in header `x-cg-pro-api-key`
  - API key in query parameter `x_cg_pro_api_key`

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

---

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