Register with Referral Code

curl -X POST "https://api.strike.markets/referral/register" \
  -H "X-API-Key: stk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "referral_code": "TRADER123"
  }'

{
  "success": true,
  "message": "Successfully registered with referral code TRADER123"
}

Overview

Register your account with a referral code to join someone’s referral network. This establishes the referral relationship and ensures both you and the referrer can earn benefits from the referral program.

This endpoint requires authentication with a valid API key. You can only register with a referral code once per account.

Referral registration is permanent and cannot be changed once set. Make sure you’re using the correct referral code before submitting.

Authentication

Include your API key in the X-API-Key header:

X-API-Key: stk_your_api_key_here

Request Body

referral_code

string

required

Valid referral code from another Strike Protocol user.Requirements:

Must be an existing, active referral code
Cannot be your own referral code
Case-insensitive matching

Example: “TRADER123”

Response Fields

success

boolean

Indicates if the referral registration was successful

message

string

Confirmation message with details about the registration

Referral Registration Rules

Eligibility Requirements

New users only: Can only register once per account
Active codes: Referral code must exist and be active
No self-referral: Cannot use your own referral code
Timing: Must register before making first trade (recommended)

Registration Process

Account creation: Create Strike Protocol account
Authentication: Obtain API key
Code validation: System validates the referral code
Network joining: You join the referrer’s network
Benefit activation: Referral benefits become active

Permanent Association

One-time only: Cannot change referrer after registration
Lifetime relationship: Benefits continue indefinitely
Network inclusion: You become part of referrer’s network

Referral Program Benefits

For New Users (You)

Welcome bonuses: May receive signup bonuses
Reduced fees: Potential trading fee discounts
Special offers: Access to referrer’s exclusive promotions
Community access: Join referrer’s trading community

For Referrers

Trading commissions: Earn percentage of your trading fees
Network growth: You join their referral network
Tier bonuses: Higher tier referrers earn more
Lifetime earnings: Continue earning as long as you trade

Multi-Tier System

Direct referrals: Referrer earns from your activity
Sub-referrals: May include multi-level commission structure
Network effects: Larger networks generate more benefits

Use Cases

Getting Started

New user onboarding: Register with a code before your first trade
Friend referrals: Join Strike using a friend’s referral code
Community participation: Use codes from content creators or communities
Promotional offers: Register with codes that offer special bonuses

Follow traders: Use codes from traders you want to follow
Join groups: Register with group or community codes
Educational content: Use codes from educators or analysts
Partnerships: Register with codes from partner organizations

Error Responses

400 Bad Request

object

Invalid request parameters or referral code format

{
  "error": 400,
  "message": "Invalid referral code format"
}

Common causes:

Empty or missing referral code
Invalid code format
Code contains invalid characters

401 Unauthorized

object

Missing or invalid authentication token

{
  "error": 401,
  "message": "Authorization header missing"
}

404 Not Found

object

Referral code does not exist

{
  "error": 404,
  "message": "Referral code 'NONEXISTENT' not found"
}

409 Conflict

object

Account already registered with a referral code or attempting self-referral

{
  "error": 409,
  "message": "Account is already registered with a referral code"
}

Or:

{
  "error": 409,
  "message": "Cannot use your own referral code"
}

429 Too Many Requests

object

Rate limit exceeded (5 requests per minute for referral endpoints)

{
  "error": 429,
  "message": "Rate limit exceeded"
}

Usage Examples

Basic Referral Registration

async function registerWithReferral(referralCode) {
  try {
    const response = await fetch('https://api.strike.markets/referral/register', {
      method: 'POST',
      headers: {
        'X-API-Key': apiKey,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        referral_code: referralCode
      })
    });

    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.message);
    }

    const result = await response.json();
    console.log(`✅ ${result.message}`);
    
    return result;
  } catch (error) {
    console.error('❌ Registration failed:', error.message);
    throw error;
  }
}

// Usage
await registerWithReferral('TRADER123');

Registration with Validation

function validateReferralCode(code) {
  if (!code || typeof code !== 'string') {
    return { valid: false, error: 'Referral code must be a non-empty string' };
  }
  
  const trimmedCode = code.trim();
  
  if (trimmedCode.length < 3) {
    return { valid: false, error: 'Referral code must be at least 3 characters long' };
  }
  
  if (trimmedCode.length > 20) {
    return { valid: false, error: 'Referral code must be no more than 20 characters long' };
  }
  
  if (!/^[a-zA-Z0-9]+$/.test(trimmedCode)) {
    return { valid: false, error: 'Referral code can only contain letters and numbers' };
  }
  
  return { valid: true, code: trimmedCode.toUpperCase() };
}

async function safeRegisterWithReferral(referralCode) {
  const validation = validateReferralCode(referralCode);
  
  if (!validation.valid) {
    throw new Error(`Invalid referral code: ${validation.error}`);
  }
  
  return await registerWithReferral(validation.code);
}

// Usage
try {
  await safeRegisterWithReferral('trader-123'); // Will fail validation
} catch (error) {
  console.error(error.message); // "Invalid referral code: Referral code can only contain letters and numbers"
}

await safeRegisterWithReferral('TRADER123'); // Will succeed

URL Parameter Processing

function getReferralCodeFromURL() {
  const urlParams = new URLSearchParams(window.location.search);
  const refCode = urlParams.get('ref') || urlParams.get('referral') || urlParams.get('code');
  
  return refCode ? refCode.toUpperCase() : null;
}

async function handleReferralFromURL() {
  const referralCode = getReferralCodeFromURL();
  
  if (!referralCode) {
    console.log('No referral code in URL');
    return null;
  }
  
  console.log(`Found referral code in URL: ${referralCode}`);
  
  try {
    return await safeRegisterWithReferral(referralCode);
  } catch (error) {
    console.error('Failed to register with URL referral code:', error.message);
    return null;
  }
}

// Usage: https://myapp.com/signup?ref=TRADER123
await handleReferralFromURL();

Registration Status Checker

class ReferralRegistration {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = 'https://api.strike.markets';
  }
  
  async register(referralCode) {
    const validation = validateReferralCode(referralCode);
    
    if (!validation.valid) {
      throw new ReferralRegistrationError(validation.error, 'VALIDATION_ERROR');
    }
    
    try {
      const response = await fetch(`${this.baseUrl}/referral/register`, {
        method: 'POST',
        headers: {
          'X-API-Key': this.apiKey,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          referral_code: validation.code
        })
      });
      
      const result = await response.json();
      
      if (!response.ok) {
        throw new ReferralRegistrationError(result.message, this.getErrorType(response.status));
      }
      
      return {
        success: true,
        message: result.message,
        referralCode: validation.code
      };
      
    } catch (error) {
      if (error instanceof ReferralRegistrationError) {
        throw error;
      }
      
      throw new ReferralRegistrationError('Network error occurred', 'NETWORK_ERROR');
    }
  }
  
  async checkRegistrationStatus(walletAddress) {
    try {
      const response = await fetch(`${this.baseUrl}/referral/${walletAddress}`);
      
      if (response.status === 404) {
        return { registered: false, canRegister: true };
      }
      
      const stats = await response.json();
      return { 
        registered: true, 
        canRegister: false, 
        referredBy: stats.referredBy || null 
      };
      
    } catch (error) {
      return { registered: false, canRegister: true, error: error.message };
    }
  }
  
  getErrorType(status) {
    switch (status) {
      case 400: return 'INVALID_REQUEST';
      case 401: return 'UNAUTHORIZED';
      case 404: return 'CODE_NOT_FOUND';
      case 409: return 'ALREADY_REGISTERED';
      case 429: return 'RATE_LIMITED';
      default: return 'UNKNOWN_ERROR';
    }
  }
}

class ReferralRegistrationError extends Error {
  constructor(message, type) {
    super(message);
    this.name = 'ReferralRegistrationError';
    this.type = type;
  }
}

// Usage
const registration = new ReferralRegistration(apiKey);

// Check if user can register
const status = await registration.checkRegistrationStatus(walletAddress);

if (status.canRegister) {
  try {
    const result = await registration.register('TRADER123');
    console.log('Registration successful:', result.message);
  } catch (error) {
    console.error(`Registration failed (${error.type}):`, error.message);
  }
} else {
  console.log('User already registered or cannot register');
}

Onboarding Flow Integration

class OnboardingFlow {
  constructor(apiKey, walletAddress) {
    this.registration = new ReferralRegistration(apiKey);
    this.walletAddress = walletAddress;
  }
  
  async handleOnboarding(referralCode = null) {
    const steps = [];
    
    // Step 1: Check current registration status
    steps.push({ step: 'checking_status', status: 'in_progress' });
    const status = await this.registration.checkRegistrationStatus(this.walletAddress);
    
    if (status.registered) {
      steps.push({ 
        step: 'checking_status', 
        status: 'completed',
        message: 'User already registered in referral program'
      });
      
      return {
        success: true,
        alreadyRegistered: true,
        steps: steps
      };
    }
    
    steps.push({ step: 'checking_status', status: 'completed' });
    
    // Step 2: Handle referral code if provided
    if (referralCode) {
      steps.push({ step: 'registering_referral', status: 'in_progress' });
      
      try {
        const result = await this.registration.register(referralCode);
        steps.push({ 
          step: 'registering_referral', 
          status: 'completed',
          message: result.message,
          referralCode: referralCode
        });
        
        return {
          success: true,
          registered: true,
          referralCode: referralCode,
          steps: steps
        };
        
      } catch (error) {
        steps.push({ 
          step: 'registering_referral', 
          status: 'failed',
          error: error.message,
          errorType: error.type
        });
        
        return {
          success: false,
          error: error.message,
          errorType: error.type,
          steps: steps
        };
      }
    }
    
    // Step 3: No referral code provided
    return {
      success: true,
      noReferral: true,
      message: 'Onboarding completed without referral code',
      steps: steps
    };
  }
  
  async processReferralLink(url) {
    // Extract referral code from various URL formats
    const patterns = [
      /[?&]ref=([^&]+)/i,
      /[?&]referral=([^&]+)/i,
      /[?&]code=([^&]+)/i,
      /\/ref\/([^\/]+)/i
    ];
    
    for (const pattern of patterns) {
      const match = url.match(pattern);
      if (match) {
        return match[1].toUpperCase();
      }
    }
    
    return null;
  }
}

// Usage in onboarding
const onboarding = new OnboardingFlow(apiKey, walletAddress);

// Process referral from URL
const referralUrl = "https://strike.markets?ref=TRADER123";
const referralCode = await onboarding.processReferralLink(referralUrl);

// Complete onboarding
const result = await onboarding.handleOnboarding(referralCode);

if (result.success) {
  if (result.registered) {
    console.log(`✅ Registered with referral code: ${result.referralCode}`);
  } else if (result.alreadyRegistered) {
    console.log('ℹ️ User already in referral program');
  } else {
    console.log('✅ Onboarding completed without referral');
  }
} else {
  console.error(`❌ Onboarding failed: ${result.error}`);
}

Integration Best Practices

User Experience

Clear instructions: Explain what referral codes are and their benefits
Optional registration: Don’t make referral codes mandatory
Error handling: Provide helpful error messages
Success feedback: Confirm successful registration

URL Handling

// Support multiple URL formats
const supportedFormats = [
  'https://strike.markets?ref=CODE123',
  'https://strike.markets?referral=CODE123',
  'https://strike.markets/signup?ref=CODE123',
  'https://myapp.com/invite/CODE123'
];

Storage and Persistence

// Store referral code temporarily if user isn't ready to register
localStorage.setItem('pending_referral_code', referralCode);

// Retrieve and register when user authenticates
const pendingCode = localStorage.getItem('pending_referral_code');
if (pendingCode && isAuthenticated) {
  await registerWithReferral(pendingCode);
  localStorage.removeItem('pending_referral_code');
}

Analytics and Tracking

// Track referral registration events
function trackReferralRegistration(referralCode, success, error = null) {
  analytics.track('referral_registration', {
    referral_code: referralCode,
    success: success,
    error: error,
    timestamp: new Date().toISOString()
  });
}

Security Considerations

Input Validation

Sanitize codes: Clean and validate all referral code input
Format checking: Ensure codes match expected format
Length limits: Enforce reasonable length restrictions
Character filtering: Only allow alphanumeric characters

Rate Limiting

Registration attempts: Limit failed registration attempts
Error handling: Don’t reveal sensitive information in errors
Monitoring: Track suspicious registration patterns

Privacy Protection

Key security: Never expose API keys in logs or client-side code
Data minimization: Only collect necessary referral data
User consent: Ensure users understand referral program terms

Edit Referral Code - Create your own referral code
Get Referral Stats - View referral network performance
Dashboard - Check points earned from referrals
Authentication - API key requirements

Register with a referral code as early as possible in your Strike Protocol journey to maximize benefits for both you and your referrer.

Referral registration is permanent and cannot be changed. Double-check the referral code before submitting your registration.

Authorizations

X-API-Key

string

header

required

Strike Protocol API key authentication

Body

application/json

referral_code

string

required

Valid referral code

Response

Referral registration successful

success

boolean

message

string

Getting Started

API Key Management

Development

Trading Operations

Account Management

Position Management

Market Data

User Systems

Analytics & Health

​Overview

​Authentication

​Request Body

​Response Fields

​Referral Registration Rules

​Eligibility Requirements

​Registration Process

​Permanent Association

​Referral Program Benefits

​For New Users (You)

​For Referrers

​Multi-Tier System

​Use Cases

​Getting Started

​Social Trading

​Error Responses

​Usage Examples

​Basic Referral Registration

​Registration with Validation

​URL Parameter Processing

​Registration Status Checker

​Onboarding Flow Integration

​Integration Best Practices

​User Experience

​URL Handling

​Storage and Persistence

​Analytics and Tracking

​Security Considerations

​Input Validation

​Rate Limiting

​Privacy Protection

​Related Endpoints

Authorizations

Body

Response

Overview

Authentication

Request Body

Response Fields

Referral Registration Rules

Eligibility Requirements

Registration Process

Permanent Association

Referral Program Benefits

For New Users (You)

For Referrers

Multi-Tier System

Use Cases

Getting Started

Social Trading

Error Responses

Usage Examples

Basic Referral Registration

Registration with Validation

URL Parameter Processing

Registration Status Checker

Onboarding Flow Integration

Integration Best Practices

User Experience

URL Handling

Storage and Persistence

Analytics and Tracking

Security Considerations

Input Validation

Rate Limiting

Privacy Protection

Related Endpoints