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

# Wallet

> GET /wallet — Rank and points for a single wallet address.

Returns the rank and points for a single wallet address within a point system.

***

## GET /wallet

### Request

```bash theme={null}
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`

```json theme={null}
{
  "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

<CodeGroup>
  ```js JavaScript theme={null}
  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`);
  }
  ```

  ```ts TypeScript theme={null}
  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`);
  }
  ```
</CodeGroup>