# 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](/core-concepts/referral-codes-vs-invite-codes.md#using-an-affiliate-code-as-a-referral-code) within a project.

{% hint style="info" %}
Referral codes are different from [affiliate codes](/developer-guide/creating-affiliate-links-or-codes.md). 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](/core-concepts/referral-codes-vs-invite-codes.md).
{% endhint %}

## List a user's referral codes

```typescript
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:

```typescript
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:

```typescript
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

```typescript
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.

```typescript
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
});
```

{% hint style="info" %}
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.
{% endhint %}

## 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](https://fuul.readme.io/reference/put_v1-user-referrers)):

```bash
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.

{% hint style="info" %}
This endpoint requires a `service_role` API key. If the user already has a referrer, the existing relationship is overwritten.
{% endhint %}

## Get user referrer

Get the current referrer for a specific user:

```typescript
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.

```typescript
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}`

## API reference

| Feature                 | API endpoint                                 | Reference                                                                        |
| ----------------------- | -------------------------------------------- | -------------------------------------------------------------------------------- |
| List user's codes       | `GET /v1/referral-codes`                     | [View](https://fuul.readme.io/reference/getreferralcodesbyowner)                 |
| Generate codes          | `POST /v1/referral-codes`                    | [View](https://fuul.readme.io/reference/generatereferralcodesbatch)              |
| Check code availability | `GET /v1/referral-codes/{code}`              | [View](https://fuul.readme.io/reference/getreferralcodesbyowner-code)            |
| Update code             | `PATCH /v1/referral-codes/{code}`            | [View](https://fuul.readme.io/reference/updatereferralcode)                      |
| Check referral status   | `GET /v1/referral-codes/status`              | [View](https://fuul.readme.io/reference/getreferralcodesbyowner-status)          |
| Use referral code       | `PATCH /v1/referral-codes/{code}/use`        | [View](https://fuul.readme.io/reference/updatereferralcode-use)                  |
| Delete referral         | `DELETE /v1/referral-codes/{code}/referrals` | [View](https://fuul.readme.io/reference/delete_v1-referral-codes-code-referrals) |
| Set referrer via API    | `PUT /v1/user-referrers`                     | [View](https://fuul.readme.io/reference/put_v1-user-referrers)                   |
| Get user referrer       | `GET /v1/user/referrer`                      | [View](https://fuul.readme.io/reference/getuserreferrer)                         |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.fuul.xyz/developer-guide/referral-codes.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.