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

• Two API keys: send:tracking_event (frontend) and optionally send:trigger_event (backend)

Step 1: Install and initialize the SDK

npm install @fuul/sdk

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.

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:

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

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.

Step 4: Let affiliates create tracking links

Give affiliates a way to generate their referral links:

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:

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

See Affiliate Links & Codes for the full API.

Step 5: Display the leaderboard

Show top affiliates ranked by token earnings:

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

{
  "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 for points and volume leaderboards.

Step 6: Show individual rewards

Display a specific user's earnings:

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

See 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

2. Fetch claim checks → Get Claim Checks

3. Submit the transaction → EVM Claiming or SVM Claiming

Next steps

Feature	Guide
Add referral codes (user-generated, permanent attribution)	Referral Codes
Enable multi-level referrals	Referrals & Attribution
Target specific user segments	Managing Audiences
Get notified on payouts	Webhooks
Add fraud prevention	Fraud Prevention