referral | Hyperliquid info

​

Parameters

​

Request body

• type (string, required) — The request type. Must be "referral" to retrieve referral information.
• user (string, required) — Address in 42-character hexadecimal format; e.g. 0x0000000000000000000000000000000000000000.

​

Response

​

Response structure

• referredBy — Information about who referred this user (if applicable)
• Contains referrer address and referral code used

• cumVlm — Cumulative volume traded by this user as a string
• unclaimedRewards — Amount of unclaimed referral rewards as a string
• claimedRewards — Amount of claimed referral rewards as a string
• builderRewards — Builder rewards earned as a string

• referrerState — State information if this user is a referrer
• rewardHistory — Legacy reward history (now returned in nonFundingLedgerUpdate)

​

Referral relationship structure

• referrer — Address of the user who made the referral
• code — Referral code that was used for the referral

​

Referrer state structure

• stage — Current stage of the referrer (e.g., “ready”, “pending”)
• data — Detailed referrer information

• code — This user’s own referral code
• referralStates — Array of users referred by this user

​

Referred users structure

• user — Address of the referred user
• timeJoined — Timestamp when the user joined via referral (milliseconds)

• cumVlm — Cumulative volume traded by the referred user
• cumRewardedFeesSinceReferred — Total fees that generated rewards since referral
• cumFeesRewardedToReferrer — Total fees rewarded to the referrer from this user

​

Reward system insights

• Unclaimed rewards represent pending rewards that can be claimed
• Claimed rewards show historical rewards already received
• Builder rewards are special rewards for ecosystem participation

• Cumulative volume shows total trading activity
• Volume directly impacts reward calculations
• Higher volume typically generates more rewards

• Rewards are generated from trading fees of referred users
• Referrers receive a percentage of fees generated by their referrals
• Fee rewards accumulate over time based on referral activity

​

Referral program analysis

​

Performance metrics

• Number of successful referrals in referralStates array
• Total volume generated by referred users
• Total rewards earned from referral activity

• Individual referred user volume and activity
• Time since referral to assess retention
• Fee generation patterns over time

• Compare unclaimed vs claimed rewards
• Analyze reward accumulation patterns
• Track builder reward opportunities

​

Network effects

• Track referral chain depth and breadth
• Analyze referral code effectiveness
• Monitor referral program adoption

• Assess how referrals contribute to overall platform volume
• Analyze volume patterns of referred vs non-referred users
• Track volume growth over time since referral

​

Reward distribution

• Calculate total rewards earned as a referrer
• Analyze reward per referral metrics
• Track reward claim patterns

• Monitor rewards earned from being referred
• Compare different referral sources
• Analyze reward accumulation rates

​

Example request

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"type": "referral", "user": "0x1442ad477ded1b0028b57621aa7b6f7eadb8f568"}' \
  https://api.hyperliquid.xyz/info

​

Example response

{
  "referredBy": {
    "referrer": "0x5ac99df645f3414876c816caa18b2d234024b487",
    "code": "TESTNET"
  },
  "cumVlm": "149428030.6628420055",
  "unclaimedRewards": "11.047361",
  "claimedRewards": "22.743781",
  "builderRewards": "0.027802",
  "referrerState": {
    "stage": "ready",
    "data": {
      "code": "TEST",
      "referralStates": [
        {
          "cumVlm": "960652.017122",
          "cumRewardedFeesSinceReferred": "196.838825",
          "cumFeesRewardedToReferrer": "19.683748",
          "timeJoined": 1679425029416,
          "user": "0x11af2b93dcb3568b7bf2b6bd6182d260a9495728"
        },
        {
          "cumVlm": "438278.672653",
          "cumRewardedFeesSinceReferred": "97.628107",
          "cumFeesRewardedToReferrer": "9.762562",
          "timeJoined": 1679423947882,
          "user": "0x3f69d170055913103a034a418953b8695e4e42fa"
        }
      ]
    }
  },
  "rewardHistory": []
}

​

Use cases

• Referral program management: Track and manage referral program participation and performance
• Reward tracking: Monitor referral rewards, claims, and accumulation patterns
• Network analysis: Analyze referral networks and their growth patterns
• Performance analytics: Generate reports on referral program effectiveness
• User engagement: Track referred user activity and retention metrics
• Commission calculation: Calculate referral commissions and fee sharing
• Compliance reporting: Maintain records of referral relationships for regulatory purposes
• Marketing analytics: Analyze the effectiveness of different referral codes and campaigns
• Volume attribution: Attribute trading volume to specific referral sources
• Reward optimization: Optimize reward structures based on referral performance data
• User onboarding: Track user acquisition through referral programs
• Retention analysis: Analyze retention rates of referred vs organic users
• Revenue sharing: Implement revenue sharing programs based on referral data
• Gamification: Create gamified referral experiences with leaderboards and achievements
• Fraud detection: Detect potential referral fraud or abuse patterns
• Partner management: Manage partnerships and affiliate relationships
• Customer lifetime value: Calculate CLV impact of referral programs
• A/B testing: Test different referral program structures and incentives
• Social trading: Build social trading features based on referral relationships
• Community building: Foster community growth through referral incentives
• Cross-platform integration: Integrate referral data with external marketing tools
• Automated rewards: Implement automated reward distribution systems
• Referral code management: Manage and track custom referral codes
• Performance benchmarking: Benchmark referral program performance against industry standards
• Tax reporting: Generate tax-related documentation for referral rewards