📊Referred Metrics

Retrieve referral performance data — which users were referred by an affiliate, how much volume they generated, and how much the referrer earned.

Referred users for a specific affiliate

Use getPayoutsByReferrer to get payout and volume information for each user referred by a specific affiliate:

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

const results = await Fuul.getPayoutsByReferrer({
  user_identifier: '0x1234...',
  user_identifier_type: 'evm_address',
  referrer_scope: 'active',   // 'active' (default) or 'all' — see below
  from_date: '2026-01-01',    // optional — ISO 8601, omit for all-time
  to_date: '2026-06-08',      // optional — must be paired with from_date
});

The response is an array of records where each key is a referred user's address. Each entry contains:

Field

Type

Description

volume

number

Total volume generated by the referred user (USD)

direct_eligible_volume

number

L1 volume from this user that triggered a payout (USD) — a subset of volume

indirect_eligible_volume

number

Volume from this user's downline (L2–L4) that triggered a payout, mapped to this L1 user (USD)

earnings

array

L1-only commission per currency, each with currency (address, chainId) and amount

total_commission_earned

array

Combined L1–L4 commission per currency (same shape as earnings)

date_joined

string | null

When the referred user first converted; null for users with no confirmed attributions

referral_code

string | null

Referral code that established this relationship, if any

user_rebate_rate

number | null

Rebate rate applied to this referred user, if set

volume is the total volume generated by the referred user. direct_eligible_volume is the subset of that volume for which a payout was actually generated — not all volume may qualify depending on incentive rules, budgets, or fraud checks.

referrer_scope: 'active' (default) returns only referred users with non-zero volume or earnings. Use 'all' to also include users who were referred but have no activity yet (volume: 0, earnings: [], date_joined: null).

Referred volume for a set of users

Use getReferredVolume to retrieve the referred volume for multiple users at once:

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

const results = await Fuul.getReferredVolume({
  user_identifiers: ['0x1234...', '0x5678...'],
  identifier_type: 'evm_address',
});