Skip to main content

User Referral API Reference

Overview​

The User Referral API provides comprehensive functionality for managing multi-tier referral relationships, tracking referral statistics, and handling commission claims. The API is designed for external developers who want to integrate referral functionality into their applications.

Authentication​

All User Referral API endpoints require authentication through HTTP cookies. The system automatically manages both accessToken and refreshToken for seamless user experience.

Authentication Headers​

Cookie: accessToken=<jwt_token>; refreshToken=<refresh_token>

User Context​

All operations are performed in the context of the authenticated user. Users can only access their own referral data and perform operations on their own account.

Base URL​

https://api.blockbet.com/graphql

API Endpoints​

The User Referral API consists of the following GraphQL operations:

Queries​

  • referralStats: Get comprehensive referral statistics for the current user
  • referralTree: Get detailed referral breakdown by tier
  • userPublicInfo: Get public information for referral sharing

Mutations​

  • claimEarningsFromReferrals: Claim available referral commissions

Rate Limiting​

The API implements rate limiting to ensure fair usage:

  • Query Operations: 100 requests per minute per user
  • Mutation Operations: 10 requests per minute per user
  • Claim Operations: 5 requests per hour per user

Error Handling​

The API uses standard GraphQL error responses with detailed error messages:

{
  "errors": [
    {
      "message": "User not found",
      "extensions": {
        "code": "USER_NOT_FOUND",
        "timestamp": "2024-01-15T10:30:00Z"
      }
    }
  ]
}

Common Error Codes​

  • USER_NOT_FOUND: User does not exist
  • USER_BLOCKED: User account is blocked
  • NO_EARNINGS_TO_CLAIM: No available earnings to claim
  • INSUFFICIENT_PERMISSIONS: User lacks required permissions
  • RATE_LIMIT_EXCEEDED: Too many requests

Data Types​

Core Types​

ReferralTier​

enum ReferralTier {
  TIER_1
  TIER_2
  TIER_3
  TIER_4
}

UserReferralInfoModel​

type UserReferralInfoModel {
  username: String!
  avatarUrl: String
  directReferralsCount: Int!
  totalIndirectReferralsCount: Int!
  referredThisWeek: Int!
  totalReferralStakes: String!
  totalEarning: String!
  totalClaimed: String!
  readyToClaim: String!
}

UserReferralTreeModel​

type UserReferralTreeModel {
  tier: ReferralTier!
  referralsCount: String!
  totalStakes: String!
  totalHouseEdge: String!
  totalEarnings: String!
}

Currency Format​

All monetary values are returned as formatted strings in USD:

  • Format: $X,XXX.XX
  • Currency: USD (converted from system currency via USDC rates)
  • Precision: 2 decimal places

Example:

{
  "totalEarning": "$1,234.56",
  "readyToClaim": "$567.89"
}

Commission System​

Commission Tiers​

TierDescriptionCommission Rate
TIER_1Direct referrals10%
TIER_2Second-level referrals3%
TIER_3Third-level referrals2%
TIER_4Fourth-level referrals1%

Game Categories​

Commissions vary by game category:

  • Category 1: Premium casino games (10%, 3%, 2%, 1%)
  • Category 2: Standard games and sports betting (10%, 3%, 2%, 1%)

Best Practices​

Performance Optimization​

  1. Cache Results: Cache referral statistics for better performance
  2. Batch Requests: Use GraphQL query batching when possible
  3. Field Selection: Only request needed fields to minimize payload

Security Considerations​

  1. Token Management: Securely store and rotate authentication tokens
  2. Rate Limiting: Implement client-side rate limiting
  3. Error Handling: Never expose sensitive error details to end users

User Experience​

  1. Real-time Updates: Use webhooks for real-time referral notifications
  2. Progressive Loading: Load referral tree data progressively
  3. Error Recovery: Implement retry logic for failed requests

Testing​

Sandbox Environment​

https://api-sandbox.blockbet.com/graphql

Test Data​

The sandbox environment provides test users and referral relationships for development and testing purposes.

Support​

For API support and questions:

Changelog​

Version 1.2.0 (Current)​

  • Added referral tree breakdown by tier
  • Improved commission calculation accuracy
  • Enhanced error handling and validation

Version 1.1.0​

  • Added commission claiming functionality
  • Implemented multi-tier referral tracking
  • Added webhook support

Version 1.0.0​

  • Initial release with basic referral statistics
  • User referral information queries
  • Authentication and authorization