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.
The token leaderboard endpoint lets you see donation activity broken down by token for a specific partner contract. Each entry includes the token details, the config that received donations, and aggregate stats.
The partner contract must belong to your developer project. Contracts owned by other projects return a 404.
Get token leaderboard
GET /{chainId}/contracts/{address}/tokens/leaderboard
Returns a paginated list of token leaderboard entries for a partner contract.
curl "https://www.donate.gg/api/v1/{chainId}/contracts/{contractAddress}/tokens/leaderboard" \
-H "donate-api-key: YOUR_API_KEY"
| Parameter | Type | Description |
|---|
chainId | integer | Chain ID where the contract is deployed (see Chains) |
address | string | Contract address (must be valid for the given chain) |
| Parameter | Type | Default | Description |
|---|
limit | integer | 50 | Results per page, max 200 |
cursor | string | - | Cursor from previous pageKey for next page |
{
"pageKey": "next_cursor_string",
"response": [
{
"partnerToken": {
"token": {
"chainId": 1,
"address": "0xA0b8...",
"name": "USD Coin",
"symbol": "USDC",
"decimals": 6
},
"creatorAddress": "0xCreator..."
},
"config": {
"id": { "hex": "0x1234...abcd", "base58": "3xYz..." },
"users": [],
"charities": [
{
"id": "charity_abc",
"slug": "red-cross",
"name": "American Red Cross",
"weight": "60",
"...": "other charity fields"
}
]
},
"stats": {
"usdDonatedE6": "50000000",
"donationCount": "10",
"firstDonationDate": "2025-06-01T00:00:00.000Z",
"lastDonationDate": "2026-03-15T00:00:00.000Z"
}
}
]
}
Response fields
partnerToken — the token and its creator.
| Field | Type | Description |
|---|
token.chainId | number | Chain the token is on |
token.address | string | Token contract address |
token.name | string | Token name |
token.symbol | string | Token symbol (e.g. USDC) |
token.decimals | number | Token decimal precision |
creatorAddress | string | Address of the token creator |
config — the donation config associated with this entry. Same shape as configs from the list configs endpoint.
stats — aggregate donation stats for this token + config pair.
| Field | Type | Description |
|---|
usdDonatedE6 | string | Total USD donated × 10^6 |
donationCount | string | Total number of donations |
firstDonationDate | string | null | ISO 8601 timestamp of first donation |
lastDonationDate | string | null | ISO 8601 timestamp of most recent donation |
Error responses
| Status | Code | Description |
|---|
400 | VALIDATION_ERROR | Invalid chain ID or contract address |
404 | NOT_FOUND | Partner contract not found or not owned by your project |
