Creates a new affiliate code for a user, enabling them to earn commissions on referred user activity.

When to Use This Endpoint

• Onboarding new affiliates into your program
• Allowing users to become affiliates through self-service signup
• Migrating existing affiliates from another system
• Creating affiliate codes programmatically during user registration

When NOT to Use This Endpoint

• Updating existing affiliate codes (use PUT /v1/affiliates/{userIdentifier})
• Checking if code is available (use GET /v1/affiliates/codes/{code}/availability)
• Creating referral codes for end-users (use POST /v1/referral_codes)

Important Constraints

• Signature Required: Must provide valid signature proving address ownership
• Code Format: Letters, numbers, and dashes only (auto-generated from name if not provided)
• Uniqueness: Code must be unique across entire project
• Name Required: Affiliate name is mandatory
• XRPL Signatures: Must provide signature_public_key for XRPL addresses

Signature Verification

Message to sign: "I confirm that I am creating the ${code} code"

Examples:

• EVM: Sign with wallet (ethers.js, web3.js, viem)
• Solana: Sign with Phantom/Solflare wallet
• XRPL: Sign with XRPL wallet (include public key)

Code Generation

If code not provided:

• Auto-generated from name parameter
• Spaces → dashes
• Special characters removed
• Example: "John Doe" → "john-doe"

Common Errors

• 400 Bad Request:
  • Invalid signature
  • Code already exists (try different code)
  • Invalid user identifier format
  • Invalid code format (must be alphanumeric with dashes)
• 403 Forbidden: API key lacks required permissions

Best Practices

• Validate signature client-side before API call
• Check code availability first using GET /v1/affiliates/codes/{code}/availability
• Provide clear code naming guidelines to affiliates
• Store affiliate info locally for faster lookups

Related Endpoints

• GET /v1/affiliates/codes/{code}/availability - Check if code exists
• PUT /v1/affiliates/{userIdentifier} - Update affiliate code
• GET /v1/affiliates/{userIdentifier} - Get affiliate data