🤝Referral Codes

Referral codes let users invite others with a simple, shareable code. The SDK provides methods to list, generate, check, use, and delete referral codes.

Referral codes are different from affiliate codes. Affiliate codes are created by affiliates to track referral link clicks. Referral codes are invite codes that establish a direct referrer-user relationship when accepted.

List a user's referral codes

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

const result = await Fuul.listUserReferralCodes({
  user_identifier: '0x1234...',
  user_identifier_type: UserIdentifierType.EvmAddress,
});

Check referral status

Check whether a user was referred and with which code:

const status = await Fuul.getReferralStatus({
  user_identifier: '0x1234...',
  user_identifier_type: UserIdentifierType.EvmAddress,
});

if (status.referred) {
  console.log('User was referred with code:', status.code);
}

Check if a code is available

const result = await Fuul.getReferralCode({ code: 'abc1234' });

if (result.available) {
  console.log('Referral code is available!');
}

Accept a referral code

When a user accepts a referral code, a permanent referrer-user relationship is created — all future conversions by this user will be attributed to the referrer.

await Fuul.useReferralCode({
  code: 'abc1234',
  user_identifier: '0x1234...',
  user_identifier_type: UserIdentifierType.EvmAddress,
  signature: '0xabc...',
  signature_message: 'I am using invite code abc1234',
  account_chain_id: 1, // Only for smart contract accounts
});

The signed message must follow this exact format: I am using invite code ${code}

Requiring a signature ensures event validity and prevents fraud. This is mandatory.

Delete a referral

Remove a referrer-user relationship. The referral code's usage count will be incremented by one (freeing up a use).

await Fuul.deleteReferral({
  code: 'abc1234',
  user_identifier: '0x1234...',
  user_identifier_type: UserIdentifierType.EvmAddress,
  referrer_identifier: '0xabcde...',
  referrer_identifier_type: UserIdentifierType.EvmAddress,
  signature: '0xabc...',
  signature_message: 'I am deleting referral for user 0x1234... from code abc1234',
});

The signed message must follow this format:

I am deleting referral for user ${user_identifier} from code ${code}