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

## 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` | —                                                                                      |