🔗Affiliate Links & Codes

Affiliates share tracking links to refer users to your project. By default, links use the affiliate's wallet address as the identifier. Fuul also lets affiliates create custom codes for cleaner, branded URLs.

# Default link (wallet address)
https://yourwebsite.com?af=0x1f9090aae28b8a3dceadf281b0f12828e676c326

# With a custom code
https://yourwebsite.com?af=my-affiliate-code

Generating tracking links

Use generateTrackingLink to build a referral URL for an affiliate:

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

const trackingLink = await Fuul.generateTrackingLink(
  'https://yourwebsite.com',  // Base URL where pageview events are implemented
  '0x1234...',                 // Affiliate's address
  'evm_address'                // Identifier type
);

// Returns: "https://yourwebsite.com?af=my-affiliate-code"

You can also append optional tracking parameters:

const trackingLink = await Fuul.generateTrackingLink(
  'https://yourwebsite.com',
  '0x1234...',
  'evm_address',
  {
    title: 'campaign-name',
    format: 'banner',
    place: 'homepage'
  }
);

Creating affiliate codes

Affiliates can create codes from the Fuul Hosted Hub, or you can add this to your own site using the SDK.

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

await Fuul.createAffiliateCode({
  userIdentifier: '0x1234...',
  identifierType: 'evm_address',
  signature: '0xabc...',
  code: 'my-affiliate-code',
  accountChainId: 1, // Only for smart contract wallets
});

The message to sign must follow this exact format:

I confirm that I am creating the ${affiliateCode} code on Fuul

Code rules

• Alphanumeric characters and dashes (-) only

• Maximum 30 characters

Error handling

Error	Cause
ValidationError	Invalid characters in the code
InvalidSignatureError	Signature doesn't match the address and message
AddressInUseError	Address already has a code registered
CodeInUseError	Code is already taken

Updating affiliate codes

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

await Fuul.updateAffiliateCode({
  userIdentifier: '0x1234...',
  identifierType: 'evm_address',
  signature: '0xabc...',
  code: 'my-new-code',
});

The message to sign must follow this exact format:

I confirm that I am updating my code to ${affiliateCode} on Fuul

Getting an affiliate's code

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

const code = await Fuul.getAffiliateCode('0x1234...', 'evm_address');
// Returns the code string, or null if none exists

Checking code availability

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

// Check if a code has NOT been registered yet
const isFree = await Fuul.isAffiliateCodeFree('my-code');
// true = available, false = taken

// Check if a code exists AND still has remaining uses
const isAvailable = await Fuul.isAffiliateCodeAvailable('my-code');