GET /leaderboard
Request
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
{
"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
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`);
});
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();
}
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;
}