๐Ÿ”Œ API & Developers

Hyperliquid referral Info API: Request, Response Fields, and Referral Discount Context

โš ๏ธ Disclosure: Some links on this page are affiliate links. If you sign up through them, I may earn a commission โ€” at no extra cost to you.
To query referral information for a Hyperliquid account, send a POST request to https://api.hyperliquid.xyz/info with a JSON body containing type: "referral" and the account address in user. The response returns the user's referral relationship, cumulative volume, reward balances, token-level state, and referrer-side state.

This article includes a Hyperliquid referral link. If you sign up through this Hyperliquid referral link, the author may receive a commission.

Request

Use the following request shape, based on the official Hyperliquid Info endpoint documentation:

POST https://api.hyperliquid.xyz/info
Content-Type: application/json

Request body:

{
  "type": "referral",
  "user": "0x0000000000000000000000000000000000000000"
}

FieldRequiredDescription
typeYesMust be "referral".
userYesThe account address to query, in 0x-prefixed hexadecimal format.
Use the actual master or sub-account address. The documentation notes that using an agent wallet address can lead to an empty result.

Example curl request:

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

Response shape

The documented response includes referral identity, cumulative volume, reward fields, token-level state, referrer state, and legacy reward history.

๐Ÿ’ก Hyperliquid

Like what you're reading? Try it yourself โ€” this link supports ChartedTrader at no cost to you.

Create a Hyperliquid account with referral code RICH888 โ†’
๐ŸŽ You receive: 4% fee discount on first $25M volume ยท per account, lifetime

{
  "referredBy": {
    "referrer": "0x5ac99df645f3414876c816caa18b2d234024b487",
    "code": "TESTNET"
  },
  "cumVlm": "149428030.6628420055",
  "unclaimedRewards": "11.047361",
  "claimedRewards": "22.743781",
  "builderRewards": "0.027802",
  "tokenToState": [
    0,
    {
      "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": []
}

The values above are the documentation's example values, not live account data.

Field meanings

FieldMeaning
referredBy.referrerAddress of the referrer associated with the queried account.
referredBy.codeReferral code associated with the referral relationship.
cumVlmCumulative volume for the queried account. In the documented example, this top-level value is marked as USDC only.
unclaimedRewardsUnclaimed referral rewards. In the documented example, this value is marked as USDC only.
claimedRewardsClaimed referral rewards. In the documented example, this value is marked as USDC only.
builderRewardsBuilder-related rewards. In the documented example, this value is marked as USDC only.
tokenToStateArray mapping token state entries. In the example, token index 0 is paired with an object containing cumVlm, unclaimedRewards, claimedRewards, and builderRewards.
referrerState.stageReferrer state stage. The example shows "ready".
referrerState.data.codeReferral code shown in the referrer state.
referrerState.data.referralStatesArray of per-referred-user state objects.
rewardHistoryLegacy reward history. The documentation notes that claimed rewards are now returned in nonFundingLedgerUpdate.
Within each referrerState.data.referralStates object:
FieldMeaning
userAddress of the referred user.
cumVlmCumulative volume for that referred user.
cumRewardedFeesSinceReferredCumulative rewarded fees since the user was referred.
cumFeesRewardedToReferrerCumulative fees rewarded to the referrer for that referred user.
timeJoinedNumeric timestamp value shown in the documented example. The provided excerpt does not specify the unit.

Referral discount and volume context

The referral response shape shown in the documentation does not include a current fee-rate field. To inspect referral-related fee fields, use the documented userFees request:

{
  "type": "userFees",
  "user": "0x0000000000000000000000000000000000000000"
}

The documented userFees response includes fields such as:

FieldMeaning
feeSchedule.referralDiscountReferral discount field in the fee schedule. The documented example shows "0.04".
activeReferralDiscountActive referral discount field for the queried account. The documented example shows "0.0".
dailyUserVlmDaily volume entries, including user and exchange volume fields.
These userFees fields are documented example values. For broader fee-rate context, including volume tiers and staking discounts, see Hyperliquid Combined Fee Rate Calculator.

Practical interpretation

When building a referral dashboard or reconciliation tool:

  1. Query type: "referral" for the account address.
  2. Use referredBy to identify the referrer and code.
  3. Use cumVlm, unclaimedRewards, claimedRewards, and builderRewards for the queried account's reward state.
  4. Use tokenToState when you need token-level reward state.
  5. Use referrerState.data.referralStates when the queried address is acting as a referrer and you need per-referred-user cumulative volume and fee fields.
  6. Treat rewardHistory as legacy data; the documentation says claimed rewards are now returned in nonFundingLedgerUpdate.
Create a Hyperliquid account with referral code RICH888 if you want to use the referral link referenced in this article.

Continue with Hyperliquid

Browse the Hyperliquid complete guide for the complete user journey.

Continue with Hyperliquid

Browse the Hyperliquid guide hub for the complete user journey.

๐Ÿงฎ Free Hyperliquid calculators

Fee Calculator โ†’
Hyperliquid vs centralized exchange fee comparison
PnL & Liquidation โ†’
Perp PnL + liquidation price
Position Size โ†’
Risk-aware position sizing for HL perps
Hyperliquid

Ready to get started? Use the link below โ€” it helps support ChartedTrader at no cost to you.

Create a Hyperliquid account with referral code RICH888 โ†’
๐ŸŽ You receive: 4% fee discount on first $25M volume ยท per account, lifetime
๐Ÿ“ˆ

About the author

I'm a systematic trader running live strategies on IB (USDJPY momentum) and Hyperliquid (crypto perps). Questions? Reach out.

๐Ÿ“š Related Articles

๐Ÿ”Œ
API & Developers

Hyperliquid userRole Info Endpoint: Request, Response Objects, and Python Example

Use the Hyperliquid info endpoint's userRole type to identify whether an address is a user, agent, vault, sub-account, or missing, and inspect the returned data fields.

November 12, 2026 โฑ 2 min read
๐Ÿ”Œ
API & Developers

Hyperliquid API: Query Borrow/Lend User and Reserve State (2026)

Query Hyperliquid's borrowLendUserState, borrowLendReserveState, and allBorrowLendReserveStates info requests, response fields, and health outputs.

November 13, 2026 โฑ 4 min read
๐Ÿ”Œ
API & Developers

Hyperliquid l2Book Info Endpoint: Order Book Depth Snapshot Request and Response

Use Hyperliquid's l2Book info request to fetch an L2 order-book snapshot, including required fields, aggregation options, and the documented response shape.

November 18, 2026 โฑ 2 min read