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"
}
| Field | Required | Description |
|---|---|---|
type | Yes | Must be "referral". |
user | Yes | The account address to query, in 0x-prefixed hexadecimal format. |
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.
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 โ
{
"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
| Field | Meaning |
|---|---|
referredBy.referrer | Address of the referrer associated with the queried account. |
referredBy.code | Referral code associated with the referral relationship. |
cumVlm | Cumulative volume for the queried account. In the documented example, this top-level value is marked as USDC only. |
unclaimedRewards | Unclaimed referral rewards. In the documented example, this value is marked as USDC only. |
claimedRewards | Claimed referral rewards. In the documented example, this value is marked as USDC only. |
builderRewards | Builder-related rewards. In the documented example, this value is marked as USDC only. |
tokenToState | Array mapping token state entries. In the example, token index 0 is paired with an object containing cumVlm, unclaimedRewards, claimedRewards, and builderRewards. |
referrerState.stage | Referrer state stage. The example shows "ready". |
referrerState.data.code | Referral code shown in the referrer state. |
referrerState.data.referralStates | Array of per-referred-user state objects. |
rewardHistory | Legacy reward history. The documentation notes that claimed rewards are now returned in nonFundingLedgerUpdate. |
referrerState.data.referralStates object:
| Field | Meaning |
|---|---|
user | Address of the referred user. |
cumVlm | Cumulative volume for that referred user. |
cumRewardedFeesSinceReferred | Cumulative rewarded fees since the user was referred. |
cumFeesRewardedToReferrer | Cumulative fees rewarded to the referrer for that referred user. |
timeJoined | Numeric 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:
| Field | Meaning |
|---|---|
feeSchedule.referralDiscount | Referral discount field in the fee schedule. The documented example shows "0.04". |
activeReferralDiscount | Active referral discount field for the queried account. The documented example shows "0.0". |
dailyUserVlm | Daily volume entries, including user and exchange volume fields. |
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:
- Query
type: "referral"for the account address. - Use
referredByto identify the referrer and code. - Use
cumVlm,unclaimedRewards,claimedRewards, andbuilderRewardsfor the queried account's reward state. - Use
tokenToStatewhen you need token-level reward state. - Use
referrerState.data.referralStateswhen the queried address is acting as a referrer and you need per-referred-user cumulative volume and fee fields. - Treat
rewardHistoryas legacy data; the documentation says claimed rewards are now returned innonFundingLedgerUpdate.
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.