# Affiliate Dashboard

The affiliate dashboard is the affiliate-facing section of your incentives hub. It gives affiliates a real-time view of their performance, earnings, and referral activity.

## Aggregate stats

Show an overview of the affiliate's activity across the program:

```typescript
import { Fuul } from '@fuul/sdk';

const stats = await Fuul.getAffiliateStats({
  user_identifier: '0x1234...',
  this_month: true, // or provide from/to for a custom date range
});
```

| Field              | Description                            |
| ------------------ | -------------------------------------- |
| `total_earnings`   | Rewards earned, per currency           |
| `referred_volume`  | USD volume generated by referred users |
| `referred_revenue` | Revenue attributed to referred users   |
| `referred_users`   | Total unique users referred            |

## New traders

Show users who converted for the first time via this affiliate:

```typescript
const newTraders = await Fuul.getAffiliateNewTraders({
  user_identifier: '0x1234...',
  this_month: true,
});
// Returns: [{ referrer_identifier, total_new_traders }]
```

## Per-referral breakdown

Show volume and earnings for each individual referred user:

```typescript
const breakdown = await Fuul.getPayoutsByReferrer({
  user_identifier: '0x1234...',
  user_identifier_type: 'evm_address',
});
```

## Leaderboard position

Show where the affiliate ranks among all affiliates in the program:

```typescript
const leaderboard = await Fuul.getPayoutsLeaderboard({
  user_identifier: '0x1234...',
  identifier_type: 'evm_address',
  user_type: 'affiliate',
});
```

## Referral tree (multi-level programs)

For multi-level referral programs, display the affiliate's full downline:

```typescript
// GET /v1/affiliate-portal/referral-tree
```

{% hint style="info" %}
Leaderboard and payout endpoints support filtering by `conversion_external_ids`. Stats endpoints (`getAffiliateStats`) use `conversion_id` and `conversion_name` instead. All endpoints support filtering by audience IDs, so affiliates can drill into performance per incentive program or segment.
{% endhint %}

## Multi-level referral stats

For programs with multi-level referral structures, the stats distinguish between referral levels:

| Level                            | Description                                          |
| -------------------------------- | ---------------------------------------------------- |
| **R1 (referred\_volume)**        | Volume from users directly referred by the affiliate |
| **R2 + R3 (multilevel\_volume)** | Volume from second and third-degree referrals        |
| **Total (total\_volume)**        | Combined R1 + R2 + R3 volume                         |

This separation lets affiliates understand how much value comes from their direct referrals vs their extended network.

## API reference

| Feature                      | API endpoint                                | Reference                                                                         |
| ---------------------------- | ------------------------------------------- | --------------------------------------------------------------------------------- |
| Aggregate stats              | `GET /v1/affiliate-portal/stats`            | [View](https://fuul.readme.io/reference/get_v1-affiliate-portal-stats)            |
| Total stats (all affiliates) | `GET /v1/affiliate-portal/total-stats`      | [View](https://fuul.readme.io/reference/get_v1-affiliate-portal-total-stats)      |
| New traders                  | `GET /v1/affiliate-portal/new-traders`      | [View](https://fuul.readme.io/reference/get_v1-affiliate-portal-new-traders)      |
| Referral tree                | `GET /v1/affiliate-portal/referral-tree`    | [View](https://fuul.readme.io/reference/get_v1-affiliate-portal-referral-tree)    |
| Global breakdown             | `GET /v1/affiliate-portal/global-breakdown` | [View](https://fuul.readme.io/reference/get_v1-affiliate-portal-global-breakdown) |
| Per-referral breakdown       | `GET /v1/payouts/by-referrer`               | [View](https://fuul.readme.io/reference/get_v1-payouts-by-referrer)               |
| Leaderboard position         | `GET /v1/payouts/leaderboard/payouts`       | [View](https://fuul.readme.io/reference/get_v1-payouts-leaderboard-payouts)       |
| Payouts summary              | `GET /v1/payouts/summary`                   | [View](https://fuul.readme.io/reference/get_v1-payouts-summary-1)                 |