📊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:

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:

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:

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:

const leaderboard = await Fuul.getPayoutsLeaderboard({
  currency_address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // required
  user_identifier: '0x1234...',
  identifier_type: 'evm_address',
  user_type: 'affiliate',
});

currency_address is required on getPayoutsLeaderboard. Rankings are per reward currency, so a program paying two tokens has two leaderboards.

Referral tree (multi-level programs)

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

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:

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

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, which returns L1 through L4 separately.

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.

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:

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:

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:

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);

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.

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.

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

tier_protection and approve_project_tier_ids are mutually exclusive — set only one per request.

API reference

Feature	API endpoint	Reference
Aggregate stats	GET /v1/affiliate-portal/stats	View
Total stats (all affiliates)	GET /v1/affiliate-portal/total-stats	View
Referral tree	GET /v1/affiliate-portal/referral-tree	View
Global breakdown	GET /v1/affiliate-portal/global-breakdown	View
Per-referral breakdown	GET /v1/payouts/by-referrer	View
Leaderboard position	GET /v1/payouts/leaderboard/payouts	View
Payouts summary	GET /v1/payouts/summary	View
Paid volumes by level	GET /v1/affiliate-portal/paid-volumes-by-level	View
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	—