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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.fuul.xyz/developer-guide/referred-metrics.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.