POST
/
info
Query a user's referral information
curl --request POST \
  --url https://api.hyperliquid.xyz/info \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "referral",
  "user": "0x1442ad477ded1b0028b57621aa7b6f7eadb8f568"
}'
{
  "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": []
}
You can only use this endpoint on the official Hyperliquid public API. It is not available through Chainstack, as the open-source node implementation does not support it yet.
The info endpoint with type: "referral" retrieves comprehensive referral information for a specific user on the Hyperliquid exchange. This endpoint provides detailed data about referral relationships, rewards, volume metrics, and referrer status, enabling thorough analysis of referral program participation and performance.
Get your own node endpoint todayStart for free and get your app to production levels immediately. No credit card required.You can sign up with your GitHub, X, Google, or Microsoft account.

​
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

The response is a comprehensive referral information object containing details about the user’s referral relationships, rewards, and referrer status.

​
Response structure

Referral relationship:
  • referredBy — Information about who referred this user (if applicable)
  • Contains referrer address and referral code used
User metrics:
  • 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
Referrer status:
  • referrerState — State information if this user is a referrer
  • rewardHistory — Legacy reward history (now returned in nonFundingLedgerUpdate)

​
Referral relationship structure

The referredBy object contains: Referrer information:
  • referrer — Address of the user who made the referral
  • code — Referral code that was used for the referral
This field is null if the user was not referred by anyone.

​
Referrer state structure

The referrerState object contains information if the user is acting as a referrer: Referrer status:
  • stage — Current stage of the referrer (e.g., “ready”, “pending”)
  • data — Detailed referrer information
Referrer data:
  • code — This user’s own referral code
  • referralStates — Array of users referred by this user

​
Referred users structure

Each entry in referralStates contains: User identification:
  • user — Address of the referred user
  • timeJoined — Timestamp when the user joined via referral (milliseconds)
Volume and activity:
  • 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

Reward types:
  • Unclaimed rewards represent pending rewards that can be claimed
  • Claimed rewards show historical rewards already received
  • Builder rewards are special rewards for ecosystem participation
Volume tracking:
  • Cumulative volume shows total trading activity
  • Volume directly impacts reward calculations
  • Higher volume typically generates more rewards
Fee-based 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

Referrer effectiveness:
  • Number of successful referrals in referralStates array
  • Total volume generated by referred users
  • Total rewards earned from referral activity
User engagement:
  • Individual referred user volume and activity
  • Time since referral to assess retention
  • Fee generation patterns over time
Reward optimization:
  • Compare unclaimed vs claimed rewards
  • Analyze reward accumulation patterns
  • Track builder reward opportunities

​
Network effects

Referral network growth:
  • Track referral chain depth and breadth
  • Analyze referral code effectiveness
  • Monitor referral program adoption
Volume impact:
  • 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

Referrer rewards:
  • Calculate total rewards earned as a referrer
  • Analyze reward per referral metrics
  • Track reward claim patterns
Referral rewards:
  • Monitor rewards earned from being referred
  • Compare different referral sources
  • Analyze reward accumulation rates

​
Example request

Shell
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

The info endpoint with type: "referral" is essential for applications that need to:
  • 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
This endpoint provides comprehensive referral intelligence, enabling sophisticated analysis and management of referral programs and relationships on the Hyperliquid platform.

Body

application/json

Response

200 - application/json

Successful response with referral information

The response is of type object.