--- updatedAt: 2026-04-22T18:44:05.000Z agentTools: projectIndex: https://fuul.readme.io/llms.txt --- # Create or update user referrer relationship Creates or overwrites a referrer-referee relationship via API. **Authentication:** - Requires API key with `service_role` scope in the `Authorization` header: `Authorization: Bearer ` - The project is automatically derived from the API key's associated project **Use cases:** - Clients that manage their own referral system (fintechs, CEXs) — sync existing referral relationships with Fuul without using SDK or referral codes flow - Projects that need manual control over referral relationships — override, correct, or manually set who referred whom **Behavior:** - If (project, user_identifier) does NOT exist in user_referrers → create the relationship - If it already exists → overwrite the referrer (replace existing) - If `referral_code` is provided, the referral code will be looked up and its `rebate_rate` will be locked into the user_referrers relationship Supports all identifier types (email, evm_address, solana_address, etc.). # OpenAPI definition ````json { "openapi": "3.0.3", "info": { "title": "Fuul API", "version": "1.0.0", "description": "# Fuul API\n\nFuul is a Web3 growth and affiliate marketing platform that enables projects\nto track referrals, manage affiliate programs, and distribute rewards across\nmultiple blockchain networks (EVM, Solana, XRPL, Sui).\n\n## Core Concepts\n\n### Events\nEvents track user actions (conversions) that trigger rewards. Send events\nwhen users complete valuable actions like trades, deposits, or purchases.\n\n### Affiliates\nAffiliates are partners who promote your project. They receive unique codes\nand earn commissions on referred user activity.\n\n### Referral Codes\nEnd-users can generate referral codes to share with friends. Both referrer\nand referee can earn rewards.\n\n### Payouts\nRewards earned through the affiliate/referral program. Can be claimed\non-chain or tracked as points.\n\n## Authentication\n\n### API Keys\nAPI keys are bound to a single project. Include in the Authorization header:\n```\nAuthorization: Bearer YOUR_API_KEY\n```\n\n## Multi-Chain Support\n\nFuul supports multiple blockchain networks. When identifying users, specify:\n- `user_identifier`: The wallet address, email, or opaque UUID\n- `user_identifier_type`: `evm_address` | `solana_address` | `sui_address` | `xrpl_address` | `stellar_address` | `email` | `uuid`\n\n## Smart Contracts\n\nFuul is an on-chain affiliate protocol. The API works in conjunction with\nsmart contracts deployed across multiple EVM networks.\n\n### Contract Architecture\n\n- **FuulManager**: Central contract that handles attributions and claims.\n Deployed once per network.\n\n- **FuulFactory**: Creates new FuulProject contracts for each project.\n\n- **FuulProject**: Per-project contracts that hold deposited funds and\n execute payouts. Address returned when creating a project.\n\nFor contract addresses per network, see:\nhttps://docs.fuul.xyz/protocol/smart-contracts\n\n### Claim Flow\n\n1. User earns rewards through referral/affiliate activity\n2. Call `GET /v1/claim-checks/totals` to see claimable amounts\n3. Call `POST /v1/claim-checks/claim` to get a signed claim message\n4. User submits the signature to `FuulManager.claim()` on-chain\n5. Funds are transferred from FuulProject to user's wallet\n\n### Resources\n\n- [Smart Contract Addresses](https://docs.fuul.xyz/protocol/smart-contracts)\n- [Protocol Contracts Source Code](https://github.com/fuul-protocol/protocol-contracts)\n- [Subgraphs](https://docs.fuul.xyz/protocol/subgraphs)\n\n## Rate Limits\n\n- Standard endpoints: 100 requests/minute\n- Batch endpoints: 10 requests/minute\n- Leaderboard endpoints: 60 requests/minute (cached for 1 minute)\n" }, "servers": [ { "url": "https://api.fuul.xyz/api" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } }, "schemas": { "IdentifierType": { "type": "string", "enum": [ "evm_address", "solana_address", "sui_address", "xrpl_address", "stellar_address", "email", "uuid" ], "example": "evm_address", "description": "The type of identifier being used for identifying the user." } } }, "paths": { "/v1/user-referrers": { "put": { "summary": "Create or update user referrer relationship", "description": "Creates or overwrites a referrer-referee relationship via API.\n\n**Authentication:**\n- Requires API key with `service_role` scope in the `Authorization` header: `Authorization: Bearer `\n- The project is automatically derived from the API key's associated project\n\n**Use cases:**\n- Clients that manage their own referral system (fintechs, CEXs) — sync existing referral relationships with Fuul without using SDK or referral codes flow\n- Projects that need manual control over referral relationships — override, correct, or manually set who referred whom\n\n**Behavior:**\n- If (project, user_identifier) does NOT exist in user_referrers → create the relationship\n- If it already exists → overwrite the referrer (replace existing)\n- If `referral_code` is provided, the referral code will be looked up and its `rebate_rate` will be locked into the user_referrers relationship\n\nSupports all identifier types (email, evm_address, solana_address, etc.).", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "user_identifier", "user_identifier_type", "referrer_identifier", "referrer_identifier_type" ], "properties": { "user_identifier": { "type": "string", "example": "referee@email.com", "description": "The identifier of the user (referee)" }, "user_identifier_type": { "$ref": "#/components/schemas/IdentifierType", "description": "The type of identifier for the user" }, "referrer_identifier": { "type": "string", "example": "referrer@email.com", "description": "The identifier of the referrer" }, "referrer_identifier_type": { "$ref": "#/components/schemas/IdentifierType", "description": "The type of identifier for the referrer" }, "referral_code": { "type": "string", "example": "ABC123", "description": "Optional referral code to associate with this relationship.\nIf provided, the code will be looked up (must exist and belong to the project),\nand its rebate_rate will be locked into the user_referrers row." } } } } } }, "responses": { "200": { "description": "OK - User referrer relationship created or updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "description": "Indicates if the operation was successful" }, "referral_code": { "type": "string", "nullable": true, "example": "ABC123", "description": "The referral code string if a referral code was provided, null otherwise" }, "referral_code_id": { "type": "string", "nullable": true, "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "description": "The referral code ID if a referral code was provided, null otherwise" }, "rebate_rate": { "type": "number", "nullable": true, "example": 0.1, "description": "The rebate rate from the referral code if provided, null otherwise" } } }, "examples": { "with_referral_code": { "summary": "Response with referral code", "value": { "success": true, "referral_code": "ABC123", "referral_code_id": "123e4567-e89b-12d3-a456-426614174000", "rebate_rate": 0.1 } }, "without_referral_code": { "summary": "Response without referral code", "value": { "success": true, "referral_code": null, "referral_code_id": null, "rebate_rate": null } } } } } }, "400": { "description": "Bad Request - Invalid identifier, user identifier cannot be the same as referrer identifier, or referral code not found" }, "401": { "description": "Unauthorized - Missing or invalid API key" }, "403": { "description": "Forbidden - API key does not have service_role scope" }, "404": { "description": "Not Found - Project not found" } }, "tags": [ "Users" ] } } } } ````