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

# Points

> GET /points — Wallet points & rank across accessible point systems.

Returns the points, rank, number of participants and blacklist status for a wallet across all point systems accessible to the API key.

Accepts a `0x` address or an ENS name — resolution is automatic.

***

## GET /points

### Request

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

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

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.rewards.so/points?address=vitalik.eth" \
    -H "Authorization: Bearer rw_your_api_key"
  ```

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

  ```python Python theme={null}
  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']}")
  ```
</CodeGroup>