> 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({
  currency_address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // required
  user_identifier: '0x1234...',
  identifier_type: 'evm_address',
  user_type: 'affiliate',
});
```

{% hint style="info" %}
`currency_address` is required on `getPayoutsLeaderboard`. Rankings are per reward currency, so a program paying two tokens has two leaderboards.
{% endhint %}

## 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
  currency_id: 'usdc-uuid',    // optional — scope earnings to one reward currency
});
```

Each row in `results` has this shape:

| Field               | Description                                               |
| ------------------- | --------------------------------------------------------- |
| `date`              | Start of the bucket, per `group_by`                       |
| `direct_volume`     | USD volume from Level 1 (direct) referrals in this bucket |
| `indirect_volume`   | USD volume from Level 2–4 referrals, combined             |
| `direct_revenue`    | Revenue attributed to Level 1 referrals                   |
| `indirect_revenue`  | Revenue attributed to Level 2–4 referrals, combined       |
| `attributions`      | Attribution event count                                   |
| `referred_users`    | Distinct referred users active in the bucket              |
| `earnings`          | Commission earned in the bucket                           |
| `earnings_currency` | Currency of `earnings`, or `null`                         |

{% hint style="warning" %}
This breakdown splits volume and revenue **direct vs indirect**, not per level. There are no `r1_volume` / `r2_volume` / `r3_volume` fields, and no bare `revenue` field. If you need a per-level split, use [Paid volumes by level](#paid-volumes-by-level), which returns L1 through L4 separately.
{% endhint %}

{% 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   |

## Milestone bonuses

Some programs pay affiliates a bonus on top of their commission when they hit a milestone. Two are available, each scoped to a set of conversions you pass as `trigger_refs` (a comma-separated list).

### Qualified user bonus

Counts the referred users that qualified for the given conversions over a window, and returns the total USD bonus owed:

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

const bonus = await Fuul.getQualifiedUserBonus({
  user_identifier: '0x1234...',
  from: '2026-01-01',        // inclusive, YYYY-MM-DD
  to: '2026-01-31',          // inclusive, YYYY-MM-DD
  trigger_refs: 'ref-1,ref-2',
  claimable_date: '2026-02-15', // optional — when the bonus becomes claimable
});

console.log(bonus.qualified_user_count, bonus.bonus_usd);
```

### High-volume taker bonus

Returns the affiliate's aggregate taker volume and the bonus it earns:

```typescript
const bonus = await Fuul.getHighVolumeTakerBonus({
  user_identifier: '0x1234...',
  trigger_refs: 'ref-1,ref-2',
  this_month: 'true',        // current calendar month in UTC
});

console.log(bonus.aggregate_taker_volume, bonus.bonus);
```

{% hint style="warning" %}
`bonus` is a display string the server has already formatted, not a number. It comes back as literal text like `"$16,000 USDT0"`, or an em dash when the affiliate is below the 50M threshold. Render it directly and don't parse it as a numeric value.
{% endhint %}

{% hint style="info" %}
`this_month` and the `from`/`to` pair are mutually exclusive on `getHighVolumeTakerBonus`. Passing both returns HTTP 400. The same rule applies to `getAffiliatePaidVolumesByLevel`, where all-time is expressed by omitting `from`, `to`, and `this_month` entirely.
{% endhint %}

## 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 %}

Affiliate responses include two read-only protection fields:

| Field                   | Description                                                                                                              |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `protection_status`     | `protected` (more than 30 days left), `expiring` (30 days or less), `expired` (lapsed within the last 7 days), or `null` |
| `protection_expires_at` | Expiry of the active protection. Omitted whenever `protection_status` is `null`                                          |

A status is only reported when the protection is actually pinning the affiliate's tier. Once it lapses, the affiliate falls back to the tier their audiences give them, not necessarily the default tier.

The list endpoint accepts `protection_statuses` (single or repeated) to filter by these values; an unknown value returns `400`. There is no value for "no protection", so affiliates with `null` drop out of any filtered result.

## 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) |
| Time-series breakdown        | `GET /v1/affiliate-portal/stats-breakdown`         | —                                                                                      |
| Qualified user bonus         | `GET /v1/affiliate-portal/qualified-user-bonus`    | —                                                                                      |
| High-volume taker bonus      | `GET /v1/affiliate-portal/high-volume-taker-bonus` | —                                                                                      |