> For the complete documentation index, see [llms.txt](https://docs.anoncoin.it/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.anoncoin.it/apis/top-holders-api.md).

# Top Holders

> 🔑 **Authentication required.** See [API Key](/apis/api-key.md) for setup and rate limits.

## `GET` /services/v2/top-holders

Returns the top holders leaderboard ranked by trading performance. Results are paginated.

```
GET https://api.anoncoin.it/services/v2/top-holders
```

***

## Pagination

Results are returned in pages. Use the `nextToken` from the response to fetch the next page.

| Field       | Description                                    |
| ----------- | ---------------------------------------------- |
| `hasMore`   | `true` if more results are available           |
| `nextToken` | Pass as a query parameter to get the next page |

**First page:**

```
GET /services/v2/top-holders
```

**Next page:**

```
GET /services/v2/top-holders?nextToken=69
```

***

## Example Request

```bash
curl --location 'https://api.anoncoin.it/services/v2/top-holders' \
  --header 'x-api-key: YOUR_API_KEY'
```

***

## Response

```json
{
    "status": true,
    "message": "Top holders fetched successfully",
    "data": {
        "holders": [
            {
                "walletAddress": "B8ooJAoPFZqKHHHcyiVAxsap6bA14brgAvwzuGxd3wCF",
                "avgHoldingTime30d": 28.08,
                "totalTradesCount": 134,
                "pnlUsd": {
                    "allTime": 7947.29
                },
                "uPnlUsd": {
                    "allTime": 17399.65
                },
                "topCoins": [
                    {
                        "symbol": "WOOF!",
                        "mint": "8F6zYQQfiacjyJZjw1J8aP7MbgAewHHKnvLD18xDdoge",
                        "hasPosition": true,
                        "imageUrl": "https://cdn.anoncoin.it/WOOF!/image.jpeg"
                    },
                    {
                        "symbol": "DOGEVAN",
                        "mint": "8RKcQhXVKKwNu6LhZJ41TJzxer7shsb9df77S4jrdoge",
                        "hasPosition": true,
                        "imageUrl": "https://cdn.anoncoin.it/DOGEVAN/image.png"
                    },
                    {
                        "symbol": "WALDOGE",
                        "mint": "D77tASqthikebejDx15MtphmZAbpU4Jxmr1JXgD2doge",
                        "hasPosition": true,
                        "imageUrl": "https://cdn.anoncoin.it/WALDOGE/image.jpeg"
                    },
                    {
                        "symbol": "KIMCHI",
                        "mint": "AWpD39myXc7emw5M9cMCofkbo92x5FKWdGHWYpZFdoge",
                        "hasPosition": true,
                        "imageUrl": "https://cdn.anoncoin.it/KIMCHI/image.png"
                    },
                    {
                        "symbol": "OLIVER",
                        "mint": "9q221pjsPFPr7YkeoM7htZ57QBGs551pcj83BXkddoge",
                        "hasPosition": true,
                        "imageUrl": "https://cdn.anoncoin.it/OLIVER/image.png"
                    }
                ]
            }
        ],
        "hasMore": true,
        "nextToken": "69"
    },
    "requestId": "ae96acc0-39da-11f1-a2da-91e753cd3157"
}
```

## Response Fields

* `status` : `true` on success.
* `message` : Status message.
* `requestId` : Unique request identifier.
* `data` :
  * `holders` : Array of holder objects.
    * `walletAddress` : Solana wallet address of the holder.
    * `avgHoldingTime30d` : Average holding time over the last 30 days (in days).
    * `totalTradesCount` : Total number of trades made.
    * `pnlUsd` :
      * `allTime` : Realized PnL in USD (all time).
    * `uPnlUsd` :
      * `allTime` : Unrealized PnL in USD (all time).
    * `topCoins` : Array of the holder's top coin positions.
      * `symbol` : Coin ticker symbol.
      * `mint` : Solana token mint address.
      * `hasPosition` : Whether the holder currently has an open position.
      * `imageUrl` : Coin logo image URL.
  * `hasMore` : Whether more results are available.
  * `nextToken` : Pagination token for the next page.