> For the complete documentation index, see [llms.txt](https://docs.fuul.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fuul.xyz/developer-guide/referral-codes.md). # 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/affiliates/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/affiliates/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 %} ## Remove a referrer via API To delete an admin-managed referrer-user relationship, use the `DELETE /api/v1/user-referrers` endpoint ([API reference](https://fuul.readme.io/reference/delete_v1-user-referrers)): ```bash 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" }' ``` {% hint style="info" %} 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. {% endhint %} ## 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`: ```bash 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:** ```json { "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`). {% hint style="warning" %} 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. {% 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', }); ``` {% hint style="info" %} The signed message must follow this exact format: `I am deleting referral for user ${user_identifier} from code ${code}` {% endhint %} ## 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](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) | | Remove referrer via API | `DELETE /v1/user-referrers` | [View](https://fuul.readme.io/reference/delete_v1-user-referrers) | | List referral relationships via API | `GET /v1/user-referrers` | [Section above](#list-referral-relationships-via-api) | | Get user referrer | `GET /v1/user/referrer` | [View](https://fuul.readme.io/reference/getuserreferrer) | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## 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= ``` 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.