# GET /token/holders/{id}

**Operation ID:** `GetTopTokenHoldersByID`

Get top token holders by pricing ID

Returns the top token holders for a token identified by its CoinGecko pricing ID (e.g. "bitcoin", "ethereum", "usd-coin"). Results are sorted by balance in descending order.

**Response fields:**
- **token**: Token metadata (name, symbol, pricing info).
- **totalSupply**: Total supply per chain.
- **addressTopHolders**: Top holders by individual address, keyed by chain.
- **entityTopHolders**: Top holders grouped by entity (only present when groupByEntity=true), keyed by chain.

**Note:** Entity objects in the response do not include `populatedTags`. Use `GET /intelligence/entity/{id}` to retrieve tags for individual entities.

## Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `groupByEntity` | query | string | No | If 'true', groups holdings by entity rather than individual addresses. Example: `"true"` |
| `limit` | query | integer | No | Maximum number of holders to return per page (default 100, max 100). offset + limit must not exceed 1000. Example: `100` |
| `offset` | query | integer | No | Number of holders to skip for pagination (default 0). Example: `0` |
| `poolAddress` | query | string | No | Optional Solana pool address. When provided, address holder unrealized PnL is calculated from this pool only. Example: `"CiLg83sX8nJQMPkRwGMZYcjbgcHxaXsL6XjZre5nmeKn"` |
| `id` | path | string | Yes | The CoinGecko pricing ID of the token. Example: `"usd-coin"` |

## Responses

- **200**: OK
  **Schema**: ([TopHolderResponse](https://arkm.com/llms/schemas/TopHolderResponse.md))

**Example:**
```json
{
  "addressTopHolders": {
    "ethereum": [
      {
        "address": {
          "address": "0x37305B1cD40574E4C5Ce33f8e8306Be057fD7341",
          "arkhamEntity": {
            "crunchbase": "https://www.crunchbase.com/organization/makerdao",
            "id": "makerdao",
            "linkedin": "https://www.linkedin.com/company/makerdao/",
            "name": "Sky (MakerDAO)",
            "note": "",
            "service": null,
            "twitter": "https://twitter.com/MakerDAO",
            "type": "cdp",
            "website": "https://makerdao.com"
          },
          "arkhamLabel": {
            "address": "0x37305B1cD40574E4C5Ce33f8e8306Be057fD7341",
            "chainType": "evm",
            "name": "LITE PSM USDC A POCKET"
          },
          "chain": "ethereum",
          "contract": false,
          "isUserAddress": false
        },
        "balance": 4453872464.461215,
        "pctOfCap": 0.06071662849686393,
        "usd": 4453872464.461215
      },
      {
        "address": {
          "address": "0xe1940f578743367F38D3f25c2D2d32D6636929B6",
          "arkhamEntity": {
            "crunchbase": "https://www.crunchbase.com/organization/binance",
            "id": "binance",
            "linkedin": "https://www.linkedin.com/company/binance",
            "name": "Binance",
            "note": "",
            "service": null,
            "twitter": "https://twitter.com/binance",
            "type": "cex",
            "website": "https://binance.com"
          },
          "arkhamLabel": {
            "address": "0xe1940f578743367F38D3f25c2D2d32D6636929B6",
            "chainType": "evm",
            "name": "SingleOwnerMSCA (Proxy)"
          },
          "chain": "ethereum",
          "contract": true,
          "isUserAddress": false
        },
        "balance": 1699999999.039577,
        "pctOfCap": 0.02317494926268423,
        "usd": 1699999999.039577
      }
    ]
  },
  "entityTopHolders": {},
  "token": {
    "identifier": {
      "pricingID": "usd-coin"
    },
    "name": "USDC",
    "price": 0.999831,
    "price24hAgo": 0.999825,
    "symbol": "usdc"
  },
  "totalSupply": {
    "ethereum": 50539998661.70982
  }
}
```
- **400**: Bad Request
- **500**: Internal Server Error

## Example

```bash
curl -X GET "https://api.arkm.com/token/holders/usd-coin?groupByEntity=true&limit=100&offset=0&poolAddress=CiLg83sX8nJQMPkRwGMZYcjbgcHxaXsL6XjZre5nmeKn" \
  -H "API-Key: YOUR_API_KEY"
```