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

# Token Leaderboard

> View public Charity Token rankings for a chain

<Badge icon="shield" color="blue" shape="pill">
  Requires <span style={{ color: '#1D4ED8', fontWeight: '800' }}>core</span> scope
</Badge>

The Charity Tokens leaderboard returns ranked token donation stats for the selected chain.

## Get token leaderboard

`GET /{chainId}/tokens/leaderboard`

```bash theme={null}
curl "https://www.donate.gg/api/v1/{chainId}/tokens/leaderboard?limit=25" \
  -H "donate-api-key: YOUR_API_KEY"
```

**Path parameters**

| Parameter | Type    | Description                                          |
| --------- | ------- | ---------------------------------------------------- |
| `chainId` | integer | Supported chain ID (see [Chains](/developer/chains)) |

**Query parameters**

| Parameter | Type    | Default | Description                                  |
| --------- | ------- | ------- | -------------------------------------------- |
| `limit`   | integer | `25`    | Results per page, max `100`                  |
| `cursor`  | string  | -       | Cursor from previous `pageKey` for next page |

**Response**

```json theme={null}
{
  "pageKey": "next_cursor_string",
  "response": [
    {
      "rank": 1,
      "chain": { "id": 1, "name": "Ethereum", "type": "EVM" },
      "token": {
        "address": "0xA0b8...",
        "name": "USD Coin",
        "symbol": "USDC",
        "decimals": 6
      },
      "stats": {
        "usdDonatedE6": "50000000",
        "donationCount": "10",
        "firstDonationDate": "2025-06-01T00:00:00.000Z",
        "lastDonationDate": "2026-03-15T00:00:00.000Z"
      },
      "creatorAddress": "0xCreator..."
    }
  ]
}
```

### Error responses

| Status | Code               | Description                          |
| ------ | ------------------ | ------------------------------------ |
| `400`  | `VALIDATION_ERROR` | Invalid chain ID or query parameters |
| `404`  | `NOT_FOUND`        | No Charity Coins exist on this chain |

## Related endpoint

If you need project-scoped leaderboard data for a donation source you own, use [Source Leaderboard](/developer/source-leaderboard).