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

# Leaderboard

> GET /leaderboard — Ranked wallet list for a point system.

Returns the full ranked leaderboard for a point system — sorted by total points, with pagination support.

Blacklisted wallets are automatically excluded.

***

## GET /leaderboard

### Request

```bash theme={null}
GET https://api.rewards.so/leaderboard?pointSystemId=your-uuid&page=1&limit=50
Authorization: Bearer rw_your_api_key
```

### Query parameters

| Parameter       | Type     | Required | Default | Description                  |
| --------------- | -------- | -------- | ------- | ---------------------------- |
| `pointSystemId` | `string` | Yes      | —       | UUID of the point system     |
| `page`          | `number` | No       | `1`     | Page number (1-indexed)      |
| `limit`         | `number` | No       | `50`    | Entries per page (max `200`) |

### Response `200`

```json theme={null}
{
  "leaderboard": [
    {
      "rank": 1,
      "address": "0x3d73d19f3daf0cd6ea798c49939336b00adff988",
      "points": 2610,
      "events": 2
    },
    {
      "rank": 2,
      "address": "0x4a3d7344cdb69a96ab5b92d293e451ce15f9a678",
      "points": 1121,
      "events": 2
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 2,
    "totalPages": 1
  }
}
```

### Response fields

| Field     | Type     | Description                                             |
| --------- | -------- | ------------------------------------------------------- |
| `rank`    | `number` | Position on the leaderboard (global, not page-relative) |
| `address` | `string` | Wallet address                                          |
| `points`  | `number` | Total points accumulated                                |
| `events`  | `number` | Total number of point events                            |

***

## Code examples

<CodeGroup>
  ```js JavaScript theme={null}
  const res = await fetch(
    `https://api.rewards.so/leaderboard?pointSystemId=${POINT_SYSTEM_ID}&limit=100`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  );
  const { leaderboard, pagination } = await res.json();

  leaderboard.forEach(({ rank, address, points }) => {
    console.log(`#${rank} ${address} — ${points} pts`);
  });
  ```

  ```ts TypeScript theme={null}
  type LeaderboardEntry = {
    rank: number;
    address: string;
    points: number;
    events: number;
  };

  type LeaderboardResponse = {
    leaderboard: LeaderboardEntry[];
    pagination: { page: number; limit: number; total: number; totalPages: number };
  };

  async function getLeaderboard(
    pointSystemId: string,
    page = 1,
    limit = 50
  ): Promise<LeaderboardResponse> {
    const url = new URL("https://api.rewards.so/leaderboard");
    url.searchParams.set("pointSystemId", pointSystemId);
    url.searchParams.set("page", String(page));
    url.searchParams.set("limit", String(limit));

    const res = await fetch(url.toString(), {
      headers: { Authorization: `Bearer ${process.env.REWARDS_API_KEY}` },
    });

    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    return res.json();
  }
  ```

  ```ts Fetch all pages theme={null}
  async function getFullLeaderboard(pointSystemId: string): Promise<LeaderboardEntry[]> {
    const all: LeaderboardEntry[] = [];
    let page = 1;

    while (true) {
      const { leaderboard, pagination } = await getLeaderboard(pointSystemId, page, 200);
      all.push(...leaderboard);
      if (page >= pagination.totalPages) break;
      page++;
    }

    return all;
  }
  ```
</CodeGroup>