Skip to main content

User Referral Queries

Overview​

The User Referral API provides several GraphQL queries for retrieving referral statistics, user information, and detailed analytics. All queries require user authentication and return data specific to the authenticated user.

referralStats Query​

Get comprehensive referral statistics for the current user including earnings, counts, and claimable amounts.

Query Definition​

query ReferralStats {
  referralStats {
    username
    avatarUrl
    directReferralsCount
    totalIndirectReferralsCount
    referredThisWeek
    totalReferralStakes
    totalEarning
    totalClaimed
    readyToClaim
    totalReferralDeposits
    level
  }
}

Response Type​

type UserReferralInfoModel {
  username: String!              // User's display name
  avatarUrl: String             // Profile picture URL (optional)
  directReferralsCount: Int!    // Number of direct referrals (tier 1)
  totalIndirectReferralsCount: Int! // Total indirect referrals (tiers 2-4)
  referredThisWeek: Int!        // New referrals this week
  totalReferralStakes: String!  // Total betting volume from referrals
  totalEarning: String!         // Total commission earned
  totalClaimed: String!         // Total commission already claimed
  readyToClaim: String!         // Available commission to claim
  totalReferralDeposits: String! // Total deposits from all referred users
  level: UserReferralLevel!     // Current user referral level
}

Example Request​

curl -X POST https://api.blockbet.com/graphql \
  -H "Content-Type: application/json" \
  -H "Cookie: accessToken=your_jwt_token" \
  -d '{
    "query": "query { referralStats { username directReferralsCount totalEarning readyToClaim } }"
  }'

Example Response​

{
  "data": {
    "referralStats": {
      "username": "player123",
      "avatarUrl": "https://cdn.blockbet.com/avatars/player123.jpg",
      "directReferralsCount": 15,
      "totalIndirectReferralsCount": 42,
      "referredThisWeek": 3,
      "totalReferralStakes": "$125,430.50",
      "totalEarning": "$2,847.65",
      "totalClaimed": "$1,200.00",
      "readyToClaim": "$1,647.65",
      "totalReferralDeposits": "$89,250.00",
      "level": "LEVEL_2"
    }
  }
}

Field Descriptions​

User Information​

  • username: The user's unique display name used for referral links
  • avatarUrl: Optional profile picture URL for display purposes

Referral Counts​

  • directReferralsCount: Users directly referred by this user (tier 1 relationships)
  • totalIndirectReferralsCount: Users referred through the referral chain (tiers 2-4)
  • referredThisWeek: Number of new referrals registered in the current week

Financial Data​

  • totalReferralStakes: Total betting volume from all referred users (formatted as USD)
  • totalEarning: Total commission earned from all referral activity
  • totalClaimed: Commission amount already claimed and withdrawn
  • readyToClaim: Available commission balance ready for claiming
  • totalReferralDeposits: Total deposits made by all referred users (formatted as USD)
  • level: Current user referral level (LEVEL_1 through LEVEL_5) determining commission rates

Use Cases​

  1. Dashboard Display: Show user's referral performance overview
  2. Earnings Tracking: Monitor commission accumulation over time
  3. Claim Validation: Check available balance before claim attempts
  4. Performance Analytics: Track referral growth and effectiveness

referralTree Query​

Get detailed referral statistics broken down by tier for comprehensive analytics.

Query Definition​

query ReferralTree {
  referralTree {
    tier
    referralsCount
    totalStakes
    totalHouseEdge
    totalEarnings
  }
}

Response Type​

type UserReferralTreeModel {
  tier: ReferralTier!           // The referral tier (TIER_1, TIER_2, etc.)
  referralsCount: String!       // Number of referrals in this tier
  totalStakes: String!          // Total betting volume for this tier
  totalHouseEdge: String!       // House edge generated by this tier
  totalEarnings: String!        // Commission earned from this tier
}

ReferralTier Enum​

enum ReferralTier {
  TIER_1    // Direct referrals (10% commission)
  TIER_2    // Second-level referrals (3% commission)
  TIER_3    // Third-level referrals (2% commission)
  TIER_4    // Fourth-level referrals (1% commission)
}

Example Request​

curl -X POST https://api.blockbet.com/graphql \
  -H "Content-Type: application/json" \
  -H "Cookie: accessToken=your_jwt_token" \
  -d '{
    "query": "query { referralTree { tier referralsCount totalStakes totalEarnings } }"
  }'

Example Response​

{
  "data": {
    "referralTree": [
      {
        "tier": "TIER_1",
        "referralsCount": "15",
        "totalStakes": "$89,250.00",
        "totalHouseEdge": "$2,677.50",
        "totalEarnings": "$2,140.25"
      },
      {
        "tier": "TIER_2",
        "referralsCount": "28",
        "totalStakes": "$45,180.50",
        "totalHouseEdge": "$1,355.42",
        "totalEarnings": "$406.63"
      },
      {
        "tier": "TIER_3",
        "referralsCount": "12",
        "totalStakes": "$18,750.00",
        "totalHouseEdge": "$562.50",
        "totalEarnings": "$112.50"
      },
      {
        "tier": "TIER_4",
        "referralsCount": "7",
        "totalStakes": "$8,420.00",
        "totalHouseEdge": "$252.60",
        "totalEarnings": "$25.26"
      }
    ]
  }
}

Field Descriptions​

Tier Information​

  • tier: The referral tier level (TIER_1 through TIER_4)

Performance Metrics​

  • referralsCount: Number of users in this specific tier
  • totalStakes: Total betting volume generated by users in this tier
  • totalHouseEdge: House edge amount generated by this tier's activity
  • totalEarnings: Commission earned specifically from this tier

Commission Calculation​

Each tier has different commission rates:

  • TIER_1: 10% of house edge
  • TIER_2: 3% of house edge
  • TIER_3: 2% of house edge
  • TIER_4: 1% of house edge

Use Cases​

  1. Performance Analysis: Analyze which tiers generate the most revenue
  2. Tier Optimization: Identify opportunities to improve specific tier performance
  3. Detailed Reporting: Generate comprehensive referral performance reports
  4. Strategy Planning: Plan referral campaigns based on tier effectiveness

userPublicInfo Query​

Get public information about a user for referral sharing purposes.

Query Definition​

query UserPublicInfo($input: UserPublicInfoInput!) {
  userPublicInfo(input: $input) {
    username
    avatarUrl
    postText
  }
}

Input Type​

input UserPublicInfoInput {
  username: String!    // Username to look up
}

Response Type​

type UserPublicInfoModel {
  username: String!      // User's display name
  avatarUrl: String     // Profile picture URL (optional)
  postText: String      // Custom referral message (optional)
}

Example Request​

curl -X POST https://api.blockbet.com/graphql \
  -H "Content-Type: application/json" \
  -H "Cookie: accessToken=your_jwt_token" \
  -d '{
    "query": "query($input: UserPublicInfoInput!) { userPublicInfo(input: $input) { username avatarUrl postText } }",
    "variables": {
      "input": {
        "username": "player123"
      }
    }
  }'

Example Response​

{
  "data": {
    "userPublicInfo": {
      "username": "player123",
      "avatarUrl": "https://cdn.blockbet.com/avatars/player123.jpg",
      "postText": "Join me on BlockBet for the best crypto gaming experience!"
    }
  }
}

Use Cases​

  1. Referral Link Generation: Get user info for creating referral links
  2. Social Sharing: Display user information in referral campaigns
  3. Custom Messages: Show personalized referral messages
  4. Profile Validation: Verify user exists before creating referral links

userReferralAndCommissionRatesLevels Query​

Get comprehensive information about all referral levels and their commission rates. This query does not require authentication and provides static configuration data.

Query Definition​

query UserReferralAndCommissionRatesLevels {
  userReferralAndCommissionRatesLevels {
    levels {
      LEVEL_1 {
        TIER_1 {
          CAT_1
          CAT_2
        }
        TIER_2 {
          CAT_1
          CAT_2
        }
        TIER_3 {
          CAT_1
          CAT_2
        }
        TIER_4 {
          CAT_1
          CAT_2
        }
      }
      LEVEL_2 {
        TIER_1 {
          CAT_1
          CAT_2
        }
        TIER_2 {
          CAT_1
          CAT_2
        }
        TIER_3 {
          CAT_1
          CAT_2
        }
        TIER_4 {
          CAT_1
          CAT_2
        }
      }
      LEVEL_3 {
        TIER_1 {
          CAT_1
          CAT_2
        }
        TIER_2 {
          CAT_1
          CAT_2
        }
        TIER_3 {
          CAT_1
          CAT_2
        }
        TIER_4 {
          CAT_1
          CAT_2
        }
      }
      LEVEL_4 {
        TIER_1 {
          CAT_1
          CAT_2
        }
        TIER_2 {
          CAT_1
          CAT_2
        }
        TIER_3 {
          CAT_1
          CAT_2
        }
        TIER_4 {
          CAT_1
          CAT_2
        }
      }
      LEVEL_5 {
        TIER_1 {
          CAT_1
          CAT_2
        }
        TIER_2 {
          CAT_1
          CAT_2
        }
        TIER_3 {
          CAT_1
          CAT_2
        }
        TIER_4 {
          CAT_1
          CAT_2
        }
      }
    }
    ranges {
      LEVEL_1
      LEVEL_2
      LEVEL_3
      LEVEL_4
      LEVEL_5
    }
  }
}

Response Type​

type UserReferralAndCommissionRatesLevelsResponse {
  levels: Levels!    // Commission rates for all levels and tiers
  ranges: Ranges!    // Deposit requirements for each level
}

type Levels {
  LEVEL_1: Tier!
  LEVEL_2: Tier!
  LEVEL_3: Tier!
  LEVEL_4: Tier!
  LEVEL_5: Tier!
}

type Tier {
  TIER_1: Category!
  TIER_2: Category!
  TIER_3: Category!
  TIER_4: Category!
}

type Category {
  CAT_1: Float!      // Commission rate for Category 1 games
  CAT_2: Float!      // Commission rate for Category 2 games
}

type Ranges {
  LEVEL_1: String!   // Formatted deposit requirement
  LEVEL_2: String!   // Formatted deposit requirement
  LEVEL_3: String!   // Formatted deposit requirement
  LEVEL_4: String!   // Formatted deposit requirement
  LEVEL_5: String!   // Formatted deposit requirement
}

Example Request​

curl -X POST https://api.blockbet.com/graphql \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query { userReferralAndCommissionRatesLevels { levels { LEVEL_1 { TIER_1 { CAT_1 CAT_2 } } } ranges { LEVEL_1 LEVEL_2 LEVEL_3 LEVEL_4 LEVEL_5 } } }"
  }'

Example Response​

{
  "data": {
    "userReferralAndCommissionRatesLevels": {
      "levels": {
        "LEVEL_1": {
          "TIER_1": { "CAT_1": 10, "CAT_2": 10 },
          "TIER_2": { "CAT_1": 3, "CAT_2": 3 },
          "TIER_3": { "CAT_1": 2, "CAT_2": 2 },
          "TIER_4": { "CAT_1": 1, "CAT_2": 1 }
        },
        "LEVEL_2": {
          "TIER_1": { "CAT_1": 12, "CAT_2": 12 },
          "TIER_2": { "CAT_1": 3.5, "CAT_2": 3.5 },
          "TIER_3": { "CAT_1": 2.5, "CAT_2": 2.5 },
          "TIER_4": { "CAT_1": 1.25, "CAT_2": 1.25 }
        },
        "LEVEL_3": {
          "TIER_1": { "CAT_1": 15, "CAT_2": 15 },
          "TIER_2": { "CAT_1": 4, "CAT_2": 4 },
          "TIER_3": { "CAT_1": 3, "CAT_2": 3 },
          "TIER_4": { "CAT_1": 1.5, "CAT_2": 1.5 }
        },
        "LEVEL_4": {
          "TIER_1": { "CAT_1": 17.5, "CAT_2": 17.5 },
          "TIER_2": { "CAT_1": 4.5, "CAT_2": 4.5 },
          "TIER_3": { "CAT_1": 3.5, "CAT_2": 3.5 },
          "TIER_4": { "CAT_1": 1.75, "CAT_2": 1.75 }
        },
        "LEVEL_5": {
          "TIER_1": { "CAT_1": 20, "CAT_2": 20 },
          "TIER_2": { "CAT_1": 6, "CAT_2": 6 },
          "TIER_3": { "CAT_1": 4, "CAT_2": 4 },
          "TIER_4": { "CAT_1": 2, "CAT_2": 2 }
        }
      },
      "ranges": {
        "LEVEL_1": "$0",
        "LEVEL_2": "$50,000",
        "LEVEL_3": "$250,000",
        "LEVEL_4": "$1,000,000",
        "LEVEL_5": "$10,000,000"
      }
    }
  }
}

Field Descriptions​

levels​

Complete commission rate structure organized by:

  • LEVEL_1 through LEVEL_5: User referral levels based on total deposits
  • TIER_1 through TIER_4: Referral tiers (direct, 2nd level, 3rd level, 4th level)
  • CAT_1 and CAT_2: Game categories with different commission rates

ranges​

Minimum deposit requirements for each level:

  • LEVEL_1: Entry level, no minimum deposits required
  • LEVEL_2: Bronze level, requires $50,000 in referral deposits
  • LEVEL_3: Silver level, requires $250,000 in referral deposits
  • LEVEL_4: Gold level, requires $1,000,000 in referral deposits
  • LEVEL_5: Platinum level, requires $10,000,000 in referral deposits

Commission Rate Examples​

LEVEL_1 (Entry Level)​

  • TIER_1 Direct Referrals: 10% commission on both game categories
  • TIER_2 Second Level: 3% commission on both game categories
  • TIER_3 Third Level: 2% commission on both game categories
  • TIER_4 Fourth Level: 1% commission on both game categories

LEVEL_5 (Platinum Level)​

  • TIER_1 Direct Referrals: 20% commission on both game categories
  • TIER_2 Second Level: 6% commission on both game categories
  • TIER_3 Third Level: 4% commission on both game categories
  • TIER_4 Fourth Level: 2% commission on both game categories

Use Cases​

  1. Commission Rate Tables: Display earning potential for different levels
  2. Level Progression: Show users what they can achieve with more referrals
  3. Marketing Materials: Create promotional content showing commission rates
  4. Administrative Tools: Understand the complete referral system structure
  5. Client Applications: Build referral calculators and earning estimators

Authentication​

This query does not require authentication and can be called by:

  • Anonymous users viewing referral information
  • Client applications displaying commission rates
  • Marketing websites showing earning potential
  • Administrative tools for system understanding

Error Handling​

Common Errors​

Authentication Required​

{
  "errors": [
    {
      "message": "Authentication required",
      "extensions": {
        "code": "UNAUTHENTICATED"
      }
    }
  ]
}

User Not Found​

{
  "errors": [
    {
      "message": "User not found",
      "extensions": {
        "code": "USER_NOT_FOUND"
      }
    }
  ]
}

Rate Limit Exceeded​

{
  "errors": [
    {
      "message": "Rate limit exceeded",
      "extensions": {
        "code": "RATE_LIMIT_EXCEEDED",
        "retryAfter": 60
      }
    }
  ]
}

Performance Considerations​

Caching​

  • referralStats: Cache for 5 minutes to reduce database load
  • referralTree: Cache for 15 minutes as tier data changes less frequently
  • userPublicInfo: Cache for 1 hour as public info is relatively static

Field Selection​

Only request fields you need to minimize response size:

# Good - minimal fields
query {
  referralStats {
    directReferralsCount
    readyToClaim
  }
}

# Avoid - requesting all fields when not needed
query {
  referralStats {
    username
    avatarUrl
    directReferralsCount
    totalIndirectReferralsCount
    referredThisWeek
    totalReferralStakes
    totalEarning
    totalClaimed
    readyToClaim
  }
}

Batch Queries​

Combine multiple queries in a single request:

query ReferralDashboard {
  referralStats {
    directReferralsCount
    totalEarning
    readyToClaim
  }
  referralTree {
    tier
    referralsCount
    totalEarnings
  }
}