0x address or an ENS name — resolution is automatic.
GET /points
Request
GET https://api.rewards.so/points?address=vitalik.eth
Authorization: Bearer rw_your_api_key
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
address | string | Yes | 0x address or ENS name (e.g. vitalik.eth) |
Response 200
{
"address": "vitalik.eth",
"ens": "vitalik.eth",
"hexAddress": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
"resolvedAt": "2026-04-18T12:00:00.000Z",
"pointSystems": [
{
"id": "e3b0c442-98fc-1c14-9afb-ed5a7b8c6f21",
"name": "My Loyalty Program",
"slug": "my-loyalty",
"points": 1500,
"events": 12,
"rank": 3,
"totalParticipants": 250,
"isBlacklisted": false,
"blacklistReason": null,
"blacklistedAt": null
}
],
"summary": {
"totalPointSystems": 1,
"totalPoints": 1500,
"blacklistedCount": 0,
"isBlacklisted": false
}
}
Response fields
Root
| Field | Type | Description |
|---|---|---|
address | string | Display address (ENS if resolved, otherwise 0x) |
ens | string | null | ENS name if resolved, otherwise null |
hexAddress | string | Lowercase 0x address |
resolvedAt | string | ISO timestamp of the resolution |
pointSystems | array | Per-point-system breakdown |
summary | object | Global aggregate |
pointSystems[]
| Field | Type | Description |
|---|---|---|
id | string | Point system UUID |
name | string | Point system name |
slug | string | null | Public leaderboard slug |
points | number | Total points accumulated |
events | number | Number of point events |
rank | number | null | Rank in this point system (null if blacklisted with no wallet entry) |
totalParticipants | number | null | Total number of wallets in this point system |
isBlacklisted | boolean | Whether the wallet is blacklisted |
blacklistReason | string | null | Reason for the blacklist |
blacklistedAt | string | null | ISO timestamp of the blacklist |
summary
| Field | Type | Description |
|---|---|---|
totalPointSystems | number | Number of point systems the wallet appears in |
totalPoints | number | Total points across all point systems |
blacklistedCount | number | Number of point systems where the wallet is blacklisted |
isBlacklisted | boolean | true if blacklisted in at least one point system |
Errors
| Status | Message | Cause |
|---|---|---|
400 | Missing required parameter: address | Missing address query parameter |
400 | Invalid address or ENS domain | Unrecognized format |
401 | Missing API key | No Authorization header |
401 | Invalid API key | Key not found |
403 | This API key does not have read permissions | Key lacks read permission |
Edge cases
Pre-emptive blacklist — if a wallet was blacklisted before receiving any points, it still appears inpointSystems with points: 0 and rank: null.
Unknown wallet — if the wallet does not appear in any point system, pointSystems will be empty and summary.totalPointSystems will be 0.
Code examples
curl "https://api.rewards.so/points?address=vitalik.eth" \
-H "Authorization: Bearer rw_your_api_key"
type PointSystemEntry = {
id: string;
name: string;
slug: string | null;
points: number;
events: number;
rank: number | null;
totalParticipants: number | null;
isBlacklisted: boolean;
blacklistReason: string | null;
blacklistedAt: string | null;
};
type WalletPoints = {
address: string;
ens: string | null;
hexAddress: string;
resolvedAt: string;
pointSystems: PointSystemEntry[];
summary: {
totalPointSystems: number;
totalPoints: number;
blacklistedCount: number;
isBlacklisted: boolean;
};
};
async function getWalletPoints(address: string): Promise<WalletPoints> {
const url = new URL("https://api.rewards.so/points");
url.searchParams.set("address", address);
const res = await fetch(url.toString(), {
headers: { Authorization: `Bearer ${process.env.REWARDS_API_KEY}` },
});
if (!res.ok) {
const { error } = await res.json();
throw new Error(`Points API error: ${error}`);
}
return res.json();
}
const data = await getWalletPoints("vitalik.eth");
console.log(`Total points: ${data.summary.totalPoints}`);
import os
import requests
def get_wallet_points(address: str) -> dict:
res = requests.get(
"https://api.rewards.so/points",
params={"address": address},
headers={"Authorization": f"Bearer {os.environ['REWARDS_API_KEY']}"},
)
res.raise_for_status()
return res.json()
data = get_wallet_points("vitalik.eth")
print(f"Total points: {data['summary']['totalPoints']}")