# Referral Program with Token Rewards

Build a complete referral program where affiliates earn token rewards for each user they bring to your platform. By the end, you'll have tracking links, wallet attribution, a leaderboard, and a claiming flow.

## Prerequisites

* A Fuul account with a project created
* Conversion events and payout rules configured in the dashboard
* A funded budget (see [How to Add a Budget](/getting-started/how-to-add-a-budget-in-fuul.md))
* Two API keys: `send:tracking_event` (frontend) and optionally `send:trigger_event` (backend)

## Step 1: Install and initialize the SDK

```bash
npm install @fuul/sdk
```

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

Fuul.init({ apiKey: 'your-send-tracking-event-key' });
```

## Step 2: Track referral visits

Call `sendPageview` on every page load. The SDK captures the referrer's affiliate code from the URL (`?af=code`) automatically.

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

function App() {
  useEffect(() => {
    Fuul.sendPageview();
  }, []);

  return <YourApp />;
}
```

## Step 3: Identify users on wallet connect

When a user connects their wallet, call `identifyUser` to link their wallet to the tracking session:

```typescript
const onWalletConnect = async (address: string, signature: string) => {
  await Fuul.identifyUser({
    identifier: address,
    identifierType: 'evm_address',
    signature,
    message: 'Sign to verify your identity',
  });
};
```

{% hint style="info" %}
At this point, attribution is complete. When this user converts (e.g., trades, deposits), Fuul automatically attributes the conversion to the referrer and calculates rewards.
{% endhint %}

## Step 4: Let affiliates create tracking links

Give affiliates a way to generate their referral links:

```typescript
const link = await Fuul.generateTrackingLink(
  'https://yourapp.com',
  affiliateAddress,
  'evm_address'
);
// Returns: "https://yourapp.com?af=affiliate-code"
```

Affiliates can also create custom branded codes:

```typescript
await Fuul.createAffiliateCode({
  userIdentifier: affiliateAddress,
  identifierType: 'evm_address',
  signature,
  code: 'my-brand',
});
// Now: https://yourapp.com?af=my-brand
```

See [Affiliate Links & Codes](/developer-guide/creating-affiliate-links-or-codes.md) for the full API.

## Step 5: Display the leaderboard

Show top affiliates ranked by token earnings:

```typescript
const leaderboard = await Fuul.getPayoutsLeaderboard({
  currency_address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
  user_type: 'affiliate',
});
```

```json
{
  "total_results": 156,
  "page": 1,
  "page_size": 10,
  "results": [
    { "address": "0x1234...", "total_amount": 5200.50, "rank": 1, "total_attributions": 48 },
    { "address": "0x5678...", "total_amount": 3100.25, "rank": 2, "total_attributions": 31 }
  ]
}
```

See [Leaderboard Data](/developer-guide/getting-leaderboard-data.md) for points and volume leaderboards.

## Step 6: Show individual rewards

Display a specific user's earnings:

```typescript
const rewards = await Fuul.getPayoutsLeaderboard({
  currency_address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
  user_identifier: address,
  identifier_type: 'evm_address',
});
```

See [Individual Rewards](/developer-guide/getting-individual-rewards.md) for history and per-conversion breakdowns.

## Step 7: Add claiming

Let users claim their token rewards onchain. The full implementation involves fetching signed claim checks and submitting a contract transaction:

1. Show claimable balances → [Claim Flow Integration](/developer-guide/claim-frontend.md)
2. Fetch claim checks → [Get Claim Checks](/developer-guide/claiming-onchain-rewards/get-claim-checks.md)
3. Submit the transaction → [EVM Claiming](/developer-guide/claiming-onchain-rewards/evm.md) or [SVM Claiming](/developer-guide/claiming-onchain-rewards/svm-solana.md)

## Next steps

| Feature                                                    | Guide                                                                  |
| ---------------------------------------------------------- | ---------------------------------------------------------------------- |
| Add referral codes (user-generated, permanent attribution) | [Referral Codes](/developer-guide/referral-codes.md)                   |
| Enable multi-level referrals                               | [Referrals & Attribution](/core-concepts/referrals-and-attribution.md) |
| Target specific user segments                              | [Managing Audiences](/developer-guide/managing-audiences.md)           |
| Get notified on payouts                                    | [Webhooks](/developer-guide/webhooks.md)                               |
| Add fraud prevention                                       | [Fraud Prevention](/core-concepts/fraud-prevention.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/tutorials/referral-program-tutorial.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.