> For the complete documentation index, see [llms.txt](https://docs.fuul.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fuul.xyz/developer-guide/affiliate-dashboard.md).

# 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 (all levels combined, includes POINT rewards)                                                          |
| `referred_volume`          | USD volume from Level 1 (direct) referrals                                                                                          |
| `r2_volume`                | USD volume from Level 2 referrals                                                                                                   |
| `r3_volume`                | USD volume from Level 3 referrals                                                                                                   |
| `r4_volume`                | USD volume from Level 4 referrals                                                                                                   |
| `multilevel_volume`        | USD volume from Level 2 + Level 3 + Level 4 referrals                                                                               |
| `total_volume`             | Combined Level 1 through Level 4 volume                                                                                             |
| `end_user_volume`          | USD volume attributed to the affiliate's own activity as an end user                                                                |
| `referred_revenue`         | Revenue attributed to Level 1 (direct) referrals                                                                                    |
| `r2_revenue`               | Revenue attributed to Level 2 referrals                                                                                             |
| `r3_revenue`               | Revenue attributed to Level 3 referrals                                                                                             |
| `r4_revenue`               | Revenue attributed to Level 4 referrals                                                                                             |
| `referred_attributions`    | Count of Level 1 attribution events (scoped to the same date range as volumes)                                                      |
| `r1_earnings`              | Confirmed payout commissions for Level 1 referrals — array of `{ amount, currency }` in native token units (excludes POINT payouts) |
| `r2_earnings`              | Confirmed payout commissions for Level 2 referrals — array of `{ amount, currency }` in native token units (excludes POINT payouts) |
| `r3_earnings`              | Confirmed payout commissions for Level 3 referrals — array of `{ amount, currency }` in native token units (excludes POINT payouts) |
| `r4_earnings`              | Confirmed payout commissions for Level 4 referrals — array of `{ amount, currency }` in native token units (excludes POINT payouts) |
| `referred_users`           | Total unique users referred                                                                                                         |
| `active_referrers`         | Same value as `referred_users` — alias for the same count                                                                           |
| `active_referred_users_r2` | Distinct referred users with attributed volume at Level 2 (same date scope as volumes)                                              |
| `active_referred_users_r3` | Distinct referred users with attributed volume at Level 3                                                                           |
| `active_referred_users_r4` | Distinct referred users with attributed volume at Level 4                                                                           |
| `total_referrers`          | All-time distinct referred users. Always returns the full historical count — not scoped by `from`/`to` or `this_month`              |
| `assigned_referrers`       | All-time referred users registered for this affiliate. Always returns the full historical count — not scoped by date filters        |
| `current_tier`             | Tier shown to the affiliate, including tier-protection overlay — `{ id, name, slug, rank }` or `null`                               |
| `effective_tier`           | Tier after audience and default rules, without protection overlay — `{ id, name, slug, rank }` or `null`                            |

## 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',
  referrer_scope: 'active', // 'active' (default) | 'all'
  from_date: '2024-01-01', // optional, ISO 8601 — must be used together with to_date
  to_date: '2024-01-31',   // optional, inclusive upper bound
});
```

`referrer_scope` controls which referred users are included: `active` (default) returns only referred users with volume or non-zero earnings; `all` also includes referred users with no attributions yet — zero volume and empty or zero earnings.

## 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
import { Fuul } from '@fuul/sdk';

const tree = await Fuul.getReferralTree({
  user_identifier: '0x1234...',
});
```

## Time-series breakdown

Show an affiliate's performance over time (volume, revenue, earnings) grouped by day, week, or month:

```typescript
const breakdown = await Fuul.getStatsBreakdown({
  user_identifier: '0x1234...',
  group_by: 'month',           // day | week | month
  date_range: '30d',           // 7d | 30d | MTD | QTD | custom
});
// Returns: { results: [{ date, r1_volume, r2_volume, r3_volume, revenue, attributions, referred_users, earnings, earnings_currency }, ...] }
```

{% hint style="info" %}
Leaderboard endpoints (`getPayoutsLeaderboard`) filter conversions via `conversion_external_ids` (array). The stats endpoints (`getAffiliateStats`, `getStatsBreakdown`) filter via `conversion_external_id` (singular, number) or `conversion_name`; the legacy `conversion_id` param on `getAffiliateStats` is deprecated. Audience filtering is only available on the project-wide `getAffiliateTotalStats` endpoint via the `audiences` array; per-affiliate endpoints do not accept audience filters.
{% endhint %}

## Multi-level referral stats

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

| Level                                                | Description                                            |
| ---------------------------------------------------- | ------------------------------------------------------ |
| **Level 1 (referred\_volume)**                       | Volume from users directly referred by the affiliate   |
| **Level 2 + Level 3 + Level 4 (multilevel\_volume)** | Volume from second, third, and fourth-degree referrals |
| **Total (total\_volume)**                            | Combined Level 1 + Level 2 + Level 3 + Level 4 volume  |

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

## Paid volumes by level

Show the volume, revenue, and attribution counts that actually drove payouts — filtered to payout-eligible conversions only, broken down by referral level:

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

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

| Field                                | Description                                                   |
| ------------------------------------ | ------------------------------------------------------------- |
| `payout_eligible_l1_volume`          | Payout-eligible trading volume from Level 1 referrals, in USD |
| `payout_eligible_l2_volume`          | Payout-eligible trading volume from Level 2 referrals, in USD |
| `payout_eligible_l3_volume`          | Payout-eligible trading volume from Level 3 referrals, in USD |
| `payout_eligible_l4_volume`          | Payout-eligible trading volume from Level 4 referrals, in USD |
| `payout_eligible_l1_revenue`         | Attributed revenue at Level 1, in USD                         |
| `payout_eligible_l2_revenue`         | Attributed revenue at Level 2, in USD                         |
| `payout_eligible_l3_revenue`         | Attributed revenue at Level 3, in USD                         |
| `payout_eligible_l4_revenue`         | Attributed revenue at Level 4, in USD                         |
| `payout_eligible_l1_attributions`    | Payout-eligible attribution event count at Level 1            |
| `payout_eligible_l2_attributions`    | Payout-eligible attribution event count at Level 2            |
| `payout_eligible_l3_attributions`    | Payout-eligible attribution event count at Level 3            |
| `payout_eligible_l4_attributions`    | Payout-eligible attribution event count at Level 4            |
| `payout_eligible_total_volume`       | Sum of L1 + L2 + L3 + L4 payout-eligible volume               |
| `payout_eligible_total_revenue`      | Sum of L1 + L2 + L3 + L4 payout-eligible revenue              |
| `payout_eligible_total_attributions` | Sum of L1 + L2 + L3 + L4 payout-eligible attribution counts   |

## Admin: manage affiliates programmatically

Create, list, and update affiliates via the API — for workflows that run outside the dashboard. Requires a project API key.

| Endpoint                               | Description                    |
| -------------------------------------- | ------------------------------ |
| `POST /api/v1/project-affiliates`      | Create a new affiliate         |
| `GET /api/v1/project-affiliates`       | List affiliates with filtering |
| `PATCH /api/v1/project-affiliates/:id` | Update affiliate properties    |

{% hint style="warning" %}
`tier_protection` and `approve_project_tier_ids` are mutually exclusive — set only one per request.
{% endhint %}

## API reference

| Feature                      | API endpoint                                     | Reference                                                                              |
| ---------------------------- | ------------------------------------------------ | -------------------------------------------------------------------------------------- |
| Aggregate stats              | `GET /v1/affiliate-portal/stats`                 | [View](https://fuul.readme.io/reference/getaffiliateportalstats)                       |
| Total stats (all affiliates) | `GET /v1/affiliate-portal/total-stats`           | [View](https://fuul.readme.io/reference/get_v1-affiliate-portal-total-stats)           |
| 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/getpayoutsbyreferrer)                          |
| Leaderboard position         | `GET /v1/payouts/leaderboard/payouts`            | [View](https://fuul.readme.io/reference/getpayoutsleaderboard)                         |
| Payouts summary              | `GET /v1/payouts/summary`                        | [View](https://fuul.readme.io/reference/getpayoutssummary)                             |
| Paid volumes by level        | `GET /v1/affiliate-portal/paid-volumes-by-level` | [View](https://fuul.readme.io/reference/get_v1-affiliate-portal-paid-volumes-by-level) |