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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.anoncoin.it/apis/top-holders-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.