# 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](https://docs.fuul.xyz/getting-started/how-to-add-a-budget-in-fuul))
* 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](https://docs.fuul.xyz/developer-guide/creating-affiliate-links-or-codes) 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](https://docs.fuul.xyz/developer-guide/getting-leaderboard-data) 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](https://docs.fuul.xyz/developer-guide/getting-individual-rewards) 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](https://docs.fuul.xyz/developer-guide/claim-frontend)
2. Fetch claim checks → [Get Claim Checks](https://docs.fuul.xyz/developer-guide/claiming-onchain-rewards/get-claim-checks)
3. Submit the transaction → [EVM Claiming](https://docs.fuul.xyz/developer-guide/claiming-onchain-rewards/evm) or [SVM Claiming](https://docs.fuul.xyz/developer-guide/claiming-onchain-rewards/svm-solana)

## Next steps

| Feature                                                    | Guide                                                                                    |
| ---------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| Add referral codes (user-generated, permanent attribution) | [Referral Codes](https://docs.fuul.xyz/developer-guide/referral-codes)                   |
| Enable multi-level referrals                               | [Referrals & Attribution](https://docs.fuul.xyz/core-concepts/referrals-and-attribution) |
| Target specific user segments                              | [Managing Audiences](https://docs.fuul.xyz/developer-guide/managing-audiences)           |
| Get notified on payouts                                    | [Webhooks](https://docs.fuul.xyz/developer-guide/webhooks)                               |
| Add fraud prevention                                       | [Fraud Prevention](https://docs.fuul.xyz/core-concepts/fraud-prevention)                 |