> ## Documentation Index
> Fetch the complete documentation index at: https://docs.donate.gg/llms.txt
> Use this file to discover all available pages before exploring further.

# Config Leaderboard

> Fetch the top donors leaderboard for a config you own

<Badge icon="shield" color="purple" shape="pill">
  Requires <span style={{ color: '#7E22CE', fontWeight: '800' }}>partner</span> scope
</Badge>

Returns a paginated top-donors leaderboard for a single config owned by your developer project.

<Note>
  This endpoint paginates with `{ entries, nextCursor }`. Most other list endpoints use
  `{ pageKey, response }`. Pass `nextCursor` back as the `cursor` query parameter.
</Note>

## Get config leaderboard

`GET /configs/{configId}/leaderboard`

```bash theme={null}
curl "https://www.donate.gg/api/v1/configs/0x1234...abcd/leaderboard?limit=50" \
  -H "donate-api-key: YOUR_API_KEY"
```

**Path parameters**

| Parameter  | Description                                   |
| ---------- | --------------------------------------------- |
| `configId` | The config ID (hex string or base58 encoding) |

**Query parameters**

| Parameter | Type    | Default | Description                                     |
| --------- | ------- | ------- | ----------------------------------------------- |
| `limit`   | integer | `50`    | Results per page, max `200`                     |
| `cursor`  | string  | -       | Cursor from previous `nextCursor` for next page |

**Response**

```json theme={null}
{
  "entries": [
    {
      "rank": 1,
      "user": {
        "username": "alice",
        "avatar": "https://..."
      },
      "wallet": {
        "chain": { "id": 101, "name": "Solana", "type": "solana" },
        "address": "DonorPubkey..."
      },
      "stats": {
        "usdDonatedE6": "25000000",
        "donationCount": "3",
        "firstDonationDate": "2025-06-01T00:00:00.000Z",
        "lastDonationDate": "2026-03-15T00:00:00.000Z"
      }
    }
  ],
  "nextCursor": "next_cursor_string"
}
```

| Field              | Type           | Description                                                      |
| ------------------ | -------------- | ---------------------------------------------------------------- |
| `entries`          | array          | Ranked donor entries                                             |
| `entries[].user`   | object \| null | Linked user profile when known; `null` for wallet-only donors    |
| `entries[].wallet` | object         | Donor wallet (`chain` + `address`)                               |
| `entries[].stats`  | object         | Aggregate donation stats for this donor on this config           |
| `nextCursor`       | string \| null | Cursor for the next page, or `null` if there are no more results |

**Error responses**

| Status | Code               | Description                                              |
| ------ | ------------------ | -------------------------------------------------------- |
| `400`  | `VALIDATION_ERROR` | Invalid config ID or query parameters                    |
| `403`  | `SCOPE_DENIED`     | The `partner` scope is not enabled for your organization |
| `403`  | `FORBIDDEN`        | Config does not belong to this developer project         |
| `404`  | `NOT_FOUND`        | No config found with the given ID                        |