> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ekiden.fi/llms.txt
> Use this file to discover all available pages before exploring further.

# Referrals & Rewards

Referral and reward endpoints provide access to referral information, referral code management, XP rewards, weekly summaries, and reward history.

These endpoints require authentication using either a JWT bearer token or API Key authentication. See the Authentication guide for details.

***

## Referral Summary

Retrieve the authenticated user's referral information.

### REST

```http theme={null}
GET /api/v1/user/referral
```

### TypeScript SDK

```ts theme={null}
const referral = await client.user.getReferralSummary();
```

The response includes:

* `referral_code`
* `referrer_code`
* `referrer_user_id`
* `downline_count`

Example response:

```json theme={null}
{
  "referral_code": "EKIDEN123",
  "referrer_code": "PARTNER42",
  "referrer_user_id": "user_abc",
  "downline_count": 12
}
```

***

## Bind a Referrer

Associate the authenticated user with a referral code.

### REST

```http theme={null}
POST /api/v1/user/referral
Content-Type: application/json
```

```json theme={null}
{
  "referral_code": "PARTNER42"
}
```

### TypeScript SDK

```ts theme={null}
await client.user.bindReferral({
  referral_code: "PARTNER42",
});
```

The response returns the updated referral summary.

> A referral can typically only be bound once. Refer to the platform rules for the current referral policy.

***

## Rewards Summary

Retrieve the user's XP balance, weekly statistics, and reward history.

### REST

```http theme={null}
GET /api/v1/user/rewards
```

### TypeScript SDK

```ts theme={null}
const rewards = await client.user.getRewardsSummary();
```

Or with optional query parameters:

```ts theme={null}
const rewards = await client.user.getRewardsSummary({
  limit: 100,
});
```

The response includes:

* `xp_balance`
* `current_week`
* `history`
* `ledger`

Example response:

```json theme={null}
{
  "xp_balance": 125000,
  "current_week": {
    "week_start": 1731283200000,
    "week_end": 1731888000000,
    "own_ps": "90000",
    "bonus_ps": "15000",
    "final_ps": "105000",
    "xp": "105000",
    "finalized": false
  },
  "history": [],
  "ledger": []
}
```

Refer to the API Reference for the complete `RewardSummaryResponse` schema.