# Referrals

Fuul lets you set up incentives to encourage affiliates, KOLs, and users to bring new participants to your project through referrals. Referrals are the core growth mechanism — they connect attribution, reward structures, and affiliate management into a single system.

## How referrals work

1. An affiliate generates a tracking link or code
2. A user clicks the link and connects their wallet → [Attribution](/core-concepts/referrals-and-attribution.md) determines which referrer gets credit
3. The user converts (trades, deposits, etc.) → rewards are calculated based on the reward structure
4. Payouts are distributed to the referrer (and optionally to the referred user)

## Referral reward structures

Once attribution is set up, you can configure how rewards flow through the referral chain:

| Structure                               | Description                                                                                    | Guide                                                                     |
| --------------------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| **Multi-level referrals**               | Reward up to 4 levels of the referral chain (direct referrer + up to 3 levels above)           | [Multi-Level Referrals](/core-concepts/referrals/multilevel-referrals.md) |
| **Sharing rewards with referred users** | Affiliates share a portion of their commission with the users they refer (double-side rewards) | [Sharing Rewards](/core-concepts/referrals/double-side-rewards.md)        |
| **Tiered rewards**                      | Different reward rates based on affiliate performance, volume, or audience segment             | [Tiers & Multipliers](/core-concepts/tiers-and-multipliers.md)            |

## Referral codes vs affiliate codes

Fuul offers two types of codes for referral tracking:

|                | Affiliate codes                                     | Referral codes                                           |
| -------------- | --------------------------------------------------- | -------------------------------------------------------- |
| **Created by** | The affiliate (with a wallet signature)             | The project (on behalf of users)                         |
| **Format**     | Custom (e.g., `my-brand`)                           | Auto-generated (7-char alphanumeric)                     |
| **Used in**    | Tracking links (`?af=code`) — automatic attribution | Accepted explicitly by the user — permanent relationship |
| **Scope**      | Cross-project                                       | Single project                                           |

See [Affiliate Codes vs Referral Codes](/core-concepts/referral-codes-vs-invite-codes.md) for the full comparison.

## Dynamic Referral Cap

Fuul supports a **dynamic referral cap** that limits how much a referrer can earn from their referral chain. Instead of unlimited accumulation, the referrer's reward is capped based on a volume multiplier applied to their own trading volume.

### How it works

The cap is calculated as:

```
Referral Cap = Referrer's Own Volume × Volume Multiplier
```

When the referrer's accumulated referral rewards reach this cap, further referral rewards are reduced or stopped until the cap resets or the referrer's own volume increases.

**Key behaviors:**

* Works for both **Points** and **Tokens** payout types
* Setting the multiplier to `null` disables the cap entirely (unlimited referral rewards)
* The cap applies per referral cycle — it does not permanently block rewards
* Higher multipliers allow referrers to earn more relative to their own activity

### Example

| Referrer | Own Volume | Multiplier | Referral Cap |
| -------- | ---------- | ---------- | ------------ |
| Alice    | $10,000    | 3×         | $30,000      |
| Bob      | $50,000    | 2×         | $100,000     |

Alice can earn up to $30,000 from her referrals before the cap kicks in. Bob can earn up to $100,000.

This mechanism prevents affiliates with minimal personal activity from earning disproportionate rewards purely through referral chains, while still rewarding active referrers who also contribute volume.

## Related pages

| Topic                             | Guide                                                                            |
| --------------------------------- | -------------------------------------------------------------------------------- |
| How attribution assigns credit    | [Attribution](/core-concepts/referrals-and-attribution.md)                       |
| Track referrals in your app (SDK) | [Tracking Referrals](/developer-guide/tracking-referrals-in-your-app.md)         |
| Create affiliate links and codes  | [Affiliate Links & Codes](/developer-guide/creating-affiliate-links-or-codes.md) |
| Manage referral codes             | [Referral Codes](/developer-guide/referral-codes.md)                             |
| Build an affiliate dashboard      | [Affiliate Dashboard](/developer-guide/affiliate-dashboard.md)                   |
| Manage affiliate applications     | [Affiliate Applications](/core-concepts/affiliate-applications.md)               |


---

# Agent Instructions: 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/core-concepts/referrals.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.