🤝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,
});

Generating referral codes

Generate 1-50 random codes (7-char alphanumeric) on behalf of a user:

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

const codes = await Fuul.generateReferralCodes({
  user_identifier: '0x1234...',
  user_identifier_type: UserIdentifierType.EvmAddress,
  quantity: 5,        // 1-50
  max_uses: 10,       // per code, or null for unlimited
});
// Returns: [{ code }, ...]

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

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.

Remove a referrer via API

To delete an admin-managed referrer-user relationship, use the DELETE /api/v1/user-referrers endpoint (API reference):

curl -X DELETE 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"
  }'

This endpoint requires a service_role API key. It removes the referrer relationship for the specified user.

Add ?force=true to the query string to force-delete all referral code associations for this user in a single call — including any that match the current referrer. Without force, the endpoint returns 422 if matching associations exist.

List referral relationships via API

If you mirror Fuul's referral data into your own systems, use GET /api/v1/user-referrers to read the project-wide referral bridge for incremental ingestion. Each result represents one direct (level 1) referrer-user relationship, with the upstream chain nested under referral_chain:

curl -X GET "https://api.fuul.xyz/api/v1/user-referrers?updated_since=2026-06-01T00:00:00Z&limit=500" \
  -H "Authorization: Bearer your-service-role-key"

Response shape:

{
  "results": [
    {
      "user_identifier": "0x1234...",
      "user_identifier_type": "evm_address",
      "referrer_identifier": "0x5678...",
      "referrer_identifier_type": "evm_address",
      "referral_chain": {
        "referrer_2": "0x9abc...",
        "referrer_3": null,
        "referrer_4": null
      },
      "referral_code": "abc1234",
      "source": "code_acceptance",
      "reason": "via_endpoint",
      "rebate_rate": "0.1",
      "created_at": "2026-06-01T14:30:00Z",
      "updated_at": "2026-06-01T14:30:00Z"
    }
  ],
  "next_cursor": "01J...",
  "count": 1
}

Field	Description
referrer_identifier / referrer_identifier_type	The direct (level 1) referrer
referral_chain.referrer_2 … referrer_4	Upstream levels 2–4, computed live at read time; null when there is no upstream referrer
rebate_rate	Rebate rate locked into the relationship (from the referral code, when present)
next_cursor	Pass back as after_id to fetch the next page; null on the last page

Query params: created_since, updated_since (ISO 8601), after_id (cursor), limit (default 500, max 1000).

This endpoint requires a service_role API key.

A change to an upstream relationship can alter a descendant's derived levels 2–4 without updating that descendant's updated_at. If you rely on updated_since for incremental syncs, run a periodic full backfill (paging with after_id and no time filter) to catch chain changes.

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 exact format: I am deleting referral for user ${user_identifier} from code ${code}

Admin: referral code lookup

Search and inspect referral codes across all users in your project (requires admin API key):

Endpoint	Description
GET /api/v1/projects/:projectId/affiliates/referral-codes	List referral codes with optional search param — ILIKE match on code or user identifier, max 200 chars
GET /api/v1/projects/:projectId/affiliates/referral-codes/stats	Aggregated stats for referral codes

API reference

Feature	API endpoint	Reference
List user's codes	GET /v1/referral-codes	View
Generate codes	POST /v1/referral-codes	View
Check code availability	GET /v1/referral-codes/{code}	View
Update code	PATCH /v1/referral-codes/{code}	View
Check referral status	GET /v1/referral-codes/status	View
Use referral code	PATCH /v1/referral-codes/{code}/use	View
Delete referral	DELETE /v1/referral-codes/{code}/referrals	View
Set referrer via API	PUT /v1/user-referrers	View
Remove referrer via API	DELETE /v1/user-referrers	View
List referral relationships via API	GET /v1/user-referrers	Section above
Get user referrer	GET /v1/user/referrer	View