🤝Referral Codes

Referral codes let projects create shareable codes for their users. When a user accepts a referral code, a permanent referrer-user relationship is created. The SDK provides methods to list, generate, check, use, and delete referral codes.

Referral codes are generated by the project on behalf of users — they are auto-generated (random 7-char alphanumeric) and scoped to a single project. Affiliate codes can also be activated as referral codes within a project.

Referral codes are different from affiliate codes. Affiliate codes are custom, created by the affiliate with a wallet signature, and embedded in tracking links (?af=code) for automatic attribution. Referral codes are project-generated and require the user to explicitly accept the code.

For a full comparison, see Affiliate Codes vs Referral Codes.

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',
  chain_id: 1, // Only for smart contract wallets
});

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

Note: the signature says "invite code" for legacy reasons — this applies to all referral codes, regardless of how your project uses them.

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

Set a referrer via API

If you manage your own referral system (e.g. a fintech or exchange with existing user relationships), you can create or update referrer-referee relationships directly through the API instead of using referral codes (API reference):

// PUT /v1/user-referrers
// Body: {
//   user_identifier, user_identifier_type,
//   referrer_identifier, referrer_identifier_type,
//   referral_code  // optional — associates the relationship with a specific code
// }

curl -X PUT https://api.fuul.xyz/api/v1/user-referrers   -H "Content-Type: application/json"   -H "Authorization: Bearer your-service-role-key"   -d '{
    "user_identifier": "0x1234...",
    "user_identifier_type": "evm_address",
    "referrer_identifier": "0x5678...",
    "referrer_identifier_type": "evm_address",
    "referral_code": "abc1234"
  }'

If you include a referral_code, the code is validated and its rebate rate is locked into the relationship. The response includes a referral_code_id you can use to trace which code established the referral.

This endpoint requires a service_role API key. If the user already has a referrer, the existing relationship is overwritten.

Get user referrer

Get the current referrer for a specific user:

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

const referrer = await Fuul.getUserReferrer({
  user_identifier: '0x1234...',
  user_identifier_type: 'evm_address',
});

Delete a referral

Allows users to remove a referral relationship they have, freeing up a use on the referral code. The referral code's usage count will be incremented by one.

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}

Resolving email recipients

When payouts are created for email identifiers but no wallet address is mapped yet, they remain in a "pending resolution" state. Use these endpoints to check for unresolved payouts and create email-to-address mappings so the rewards can be claimed.

List emails with pending unresolved payouts (API reference):

Create mappings to resolve pending payouts to wallet addresses (API reference):

Once a mapping is created, pending movements for that email are asynchronously resolved to the target address. You can send up to 100 mappings per request.