Apply a referral code to a user, establishing a referral relationship between the user and the code owner.

When to Use This Endpoint

• Onboarding new users: Apply referral codes during user registration or first-time wallet connection
• Referral attribution: Link users to their referrer to enable reward distribution
• Viral growth tracking: Track which affiliates/campaigns are bringing new users
• Code redemption flows: Complete the referral code redemption after validation (GET /v1/referral_codes/{code})
• Campaign tracking: Attribute users to specific marketing campaigns via codes

When NOT to Use This Endpoint

• Don't use for existing referred users: Users can only use ONE referral code ever. Subsequent calls will fail with 422 error
• Don't use without signature verification: This endpoint REQUIRES a cryptographic signature from the user's wallet to prove ownership
• Don't use for code validation only: Use GET /v1/referral_codes/{code} for checking code availability without applying it
• Don't retry on 422 errors: 422 errors indicate business logic failures (code exhausted, user already referred, etc.) that cannot be resolved by retrying

How It Works

1. Signature Verification: Verifies the user owns the wallet/identifier by checking their signature
2. Code Validation: Checks if the code exists and has remaining uses
3. User Check: Verifies the user hasn't already used a referral code (one code per user, ever)
4. Relationship Creation: Establishes a permanent referral link between the user and the code owner
5. Usage Increment: Increments the code's usage counter

Important Constraints

• Required API Key Scope: referral_codes:read
• Signature Required: Must provide a valid cryptographic signature proving wallet ownership
• Exact Message Format: The signed message MUST be exactly "I am using referral code {code}" (replace {code} with actual code)
• Case-Sensitive Code: Code parameter must match exactly (ABC1234 ≠ abc1234)
• One Code Per User: Each user can only use ONE referral code in their lifetime (even if the first code is exhausted)
• Code Availability: Code must exist and have remaining uses (or unlimited uses)
• Rate Limit: 100 requests/minute (standard rate)
• Idempotency: NOT idempotent - retrying will fail with 422 if user already referred

Signature Requirements

EVM Chains (Ethereum, Polygon, BSC, etc.):

• Sign message: "I am using referral code ABC1234" (replace ABC1234 with actual code)
• Use personal_sign or equivalent wallet method
• Optionally provide chain_id for additional verification
• Signature format: 0x-prefixed hex string (e.g., 0x1234567890abcdef...)

Solana:

• Sign the UTF-8 bytes of the message
• Signature format: Base58-encoded string

XRPL/Sui:

• Follow platform-specific signature standards
• Provide signature as required by the blockchain's signature format

Common Errors

• 400 Bad Request:

  • Invalid user_identifier format
  • Malformed signature
  • Missing required fields

• 401 Unauthorized:

  • Missing or invalid API key
  • API key lacks referral_codes:read scope

• 422 Unprocessable Entity (Business Logic Errors):

  • Invalid signature: Signature verification failed (user doesn't own the wallet)
  • Invalid signature message: Message format incorrect (must be exactly "I am using referral code {code}")
  • Code not found: The referral code doesn't exist in the system
  • Code exhausted: Code has reached max_uses limit
  • User already has a referrer: User has already used a referral code before (cannot use another)

• 429 Too Many Requests: Rate limit exceeded (100 requests/minute)

Related Endpoints

• GET /v1/referral_codes/{code} - Validate code availability before attempting to use it (recommended first step)
• GET /v1/referral_codes/status - Check if a user has already used a referral code
• GET /v1/referral_codes - Get all codes owned by a specific user
• POST /v1/referral_codes - Generate new referral codes

Best Practices

1. Always validate first: Call GET /v1/referral_codes/{code} before showing the "use code" UI to users
2. Check existing status: Call GET /v1/referral_codes/status to check if user already used a code (prevent unnecessary signature requests)
3. Provide clear error messages: When 422 errors occur, explain to users why the code failed (already used a code, code expired, etc.)
4. Use correct signature format: Ensure your wallet integration generates signatures in the correct format for the blockchain
5. Don't retry 422 errors: These are permanent business logic failures that cannot be fixed by retrying
6. Verify message format: Double-check the signature_message matches exactly: "I am using referral code {CODE}"

Example Flow

1. User enters code "ABC1234" in your UI
2. GET /v1/referral_codes/ABC1234 → Check if available
3. GET /v1/referral_codes/status?user_identifier=0x123... → Check if user already referred
4. Request wallet signature for message: "I am using referral code ABC1234"
5. PATCH /v1/referral_codes/ABC1234/use → Apply the code with signature
6. Handle success (204) or failure (422)