GET /wallet
Request
GET https://api.rewards.so/wallet?pointSystemId=your-uuid&address=0xabc123...
Authorization: Bearer rw_your_api_key
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
pointSystemId | string | Yes | UUID of the point system |
address | string | Yes | Wallet address to look up |
Response 200
{
"address": "0x3d73d19f3daf0cd6ea798c49939336b00adff988",
"points": 2610,
"events": 2,
"rank": 1
}
Response fields
| Field | Type | Description |
|---|---|---|
address | string | Wallet address (normalized to lowercase) |
points | number | Total points accumulated |
events | number | Total number of point events |
rank | number | Current rank on the leaderboard |
Errors
| Status | Message | Cause |
|---|---|---|
404 | Wallet not found in this point system | Address has never received points or been registered |
Code examples
const res = await fetch(
`https://api.rewards.so/wallet?pointSystemId=${POINT_SYSTEM_ID}&address=${walletAddress}`,
{ headers: { Authorization: `Bearer ${API_KEY}` } }
);
if (res.status === 404) {
console.log("Wallet not found — user has no points yet");
} else {
const { rank, points } = await res.json();
console.log(`Rank #${rank} with ${points} points`);
}
type WalletStats = {
address: string;
points: number;
events: number;
rank: number;
};
async function getWalletStats(
pointSystemId: string,
address: string
): Promise<WalletStats | null> {
const url = new URL("https://api.rewards.so/wallet");
url.searchParams.set("pointSystemId", pointSystemId);
url.searchParams.set("address", address);
const res = await fetch(url.toString(), {
headers: { Authorization: `Bearer ${process.env.REWARDS_API_KEY}` },
});
if (res.status === 404) return null;
if (!res.ok) throw new Error(`HTTP ${res.status}`);
return res.json();
}
// Usage
const stats = await getWalletStats(POINT_SYSTEM_ID, userWalletAddress);
if (!stats) {
// New user — no points yet
} else {
console.log(`You are rank #${stats.rank} with ${stats.points} pts`);
}