> 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/referred-metrics.md).

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

```typescript
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                                              |

{% hint style="info" %}
`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.
{% endhint %}

{% hint style="info" %}
`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`).
{% endhint %}

## Referred volume for a set of users

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

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

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

## Referred volume leaderboard

To get the full referred volume leaderboard, use the volume leaderboard with `user_type = 'affiliate'`:

{% content-ref url="/pages/DzzfdNeaVZLSZSvN0K8Q" %}
[Volume](/developer-guide/getting-leaderboard-data/volume.md)
{% endcontent-ref %}

## API reference

| Feature             | API endpoint                                  | Reference                                                                           |
| ------------------- | --------------------------------------------- | ----------------------------------------------------------------------------------- |
| Payouts by referrer | `GET /v1/payouts/by-referrer`                 | [View](https://fuul.readme.io/reference/getpayoutsbyreferrer)                       |
| Referred volume     | `GET /v1/payouts/leaderboard/referred-volume` | [View](https://fuul.readme.io/reference/get_v1-payouts-leaderboard-referred-volume) |