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

# Source Leaderboard

> View donation subject stats for a donation source owned by your project

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

The source leaderboard endpoint returns ranked donation subjects (currently token subjects) for a specific donation source contract.

This endpoint is scoped to your developer project. If the donation source is not owned by your project, the API returns `404`.

## Get source leaderboard

`GET /{chainId}/donationSources/{address}/subjects/leaderboard`

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

**Path parameters**

| Parameter | Type    | Description                                               |
| --------- | ------- | --------------------------------------------------------- |
| `chainId` | integer | Chain ID where the donation source is deployed            |
| `address` | string  | Donation source contract address (canonicalized by chain) |

**Query parameters**

| Parameter              | Type                                   | Default         | Description                                         |
| ---------------------- | -------------------------------------- | --------------- | --------------------------------------------------- |
| `limit`                | integer                                | `25`            | Results per page, max `100`                         |
| `cursor`               | string                                 | -               | Cursor from previous `pageKey` for next page        |
| `sortBy`               | `"top-donated"` \| `"recent-donation"` | `"top-donated"` | Sort order for leaderboard results                  |
| `includeInappropriate` | `"true"` \| `"false"`                  | `"true"`        | Whether to include entries flagged as inappropriate |

**Response**

```json theme={null}
{
  "pageKey": "next_cursor_string",
  "response": [
    {
      "rank": 1,
      "chain": { "id": 101, "name": "Solana", "type": "solana" },
      "type": "token",
      "token": {
        "address": "So11...",
        "name": "Example Token",
        "symbol": "EXMP",
        "decimals": 6
      },
      "creatorAddress": "CreatorPubkey...",
      "stats": {
        "usdDonatedE6": "50000000",
        "donationCount": "10",
        "firstDonationDate": "2025-06-01T00:00:00.000Z",
        "lastDonationDate": "2026-03-15T00:00:00.000Z"
      }
    }
  ]
}
```

### Error responses

| Status | Code               | Description                                                  |
| ------ | ------------------ | ------------------------------------------------------------ |
| `400`  | `VALIDATION_ERROR` | Invalid chain ID, source address, or query parameters        |
| `404`  | `NOT_FOUND`        | Donation source not found or does not belong to your project |