# referral

## POST /info

> Request user referral.

```json
{"openapi":"3.1.1","info":{"title":"Hyperliquid API - info/referral","version":"1.0.0"},"tags":[{"name":"referral"}],"servers":[{"url":"https://api.hyperliquid.xyz","description":"Mainnet"},{"url":"https://api.hyperliquid-testnet.xyz","description":"Testnet"}],"paths":{"/info":{"post":{"tags":["referral"],"description":"Request user referral.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"description":"Type of request.","enum":["referral"]},"user":{"type":"string","pattern":"^0[xX][0-9a-fA-F]+$","minLength":42,"maxLength":42,"description":"User address."}},"required":["type","user"],"description":"Request user referral."}}},"required":true},"responses":{"200":{"description":"Referral details for a user.","content":{"application/json":{"schema":{"type":"object","properties":{"referredBy":{"anyOf":[{"type":"object","properties":{"referrer":{"type":"string","pattern":"^0[xX][0-9a-fA-F]+$","minLength":42,"maxLength":42,"description":"Referrer address."},"code":{"type":"string","minLength":1,"description":"Referral code used."}},"required":["referrer","code"],"nullable":true}],"description":"Referrer details."},"cumVlm":{"type":"string","pattern":"^[0-9]+(\\.[0-9]+)?$","description":"Cumulative traded volume."},"unclaimedRewards":{"type":"string","pattern":"^[0-9]+(\\.[0-9]+)?$","description":"Rewards earned but not yet claimed."},"claimedRewards":{"type":"string","pattern":"^[0-9]+(\\.[0-9]+)?$","description":"Rewards that have been claimed."},"builderRewards":{"type":"string","pattern":"^[0-9]+(\\.[0-9]+)?$","description":"Builder reward amount."},"referrerState":{"oneOf":[{"type":"object","properties":{"stage":{"description":"Referrer is ready to receive rewards.","enum":["ready"]},"data":{"type":"object","properties":{"code":{"type":"string","minLength":1,"description":"Assigned referral code."},"nReferrals":{"type":"integer","minimum":0,"description":"Total number of referrals."},"referralStates":{"type":"array","items":{"type":"object","properties":{"cumVlm":{"type":"string","pattern":"^[0-9]+(\\.[0-9]+)?$","description":"Cumulative traded volume."},"cumRewardedFeesSinceReferred":{"type":"string","pattern":"^[0-9]+(\\.[0-9]+)?$","description":"Total fees rewarded to the referred user since referral."},"cumFeesRewardedToReferrer":{"type":"string","pattern":"^[0-9]+(\\.[0-9]+)?$","description":"Total fees rewarded to the referrer from referred trades."},"timeJoined":{"type":"integer","minimum":0,"description":"Timestamp when the referred user joined (in ms since epoch)."},"user":{"type":"string","pattern":"^0[xX][0-9a-fA-F]+$","minLength":42,"maxLength":42,"description":"Address of the referred user."},"tokenToState":{"type":"array","items":{"type":"array","items":[{"type":"integer","minimum":0},{"type":"object","properties":{"cumVlm":{"type":"string","pattern":"^[0-9]+(\\.[0-9]+)?$","description":"Cumulative traded volume."},"cumRewardedFeesSinceReferred":{"type":"string","pattern":"^[0-9]+(\\.[0-9]+)?$","description":"Total fees rewarded to the referred user since referral."},"cumFeesRewardedToReferrer":{"type":"string","pattern":"^[0-9]+(\\.[0-9]+)?$","description":"Total fees rewarded to the referrer from referred trades."}},"required":["cumVlm","cumRewardedFeesSinceReferred","cumFeesRewardedToReferrer"]}],"minItems":2,"description":"Tuple of token ID and its referral reward state."},"description":"Mapping of token IDs to referral reward states."}},"required":["cumVlm","cumRewardedFeesSinceReferred","cumFeesRewardedToReferrer","timeJoined","user","tokenToState"],"description":"Referral state for a referred user."},"description":"Summary of each referral state."}},"required":["code","nReferrals","referralStates"],"description":"Referral program details."}},"required":["stage","data"]},{"type":"object","properties":{"stage":{"description":"Referrer needs to create a referral code.","enum":["needToCreateCode"]}},"required":["stage"]},{"type":"object","properties":{"stage":{"description":"Referrer must complete a trade before earning rewards.","enum":["needToTrade"]},"data":{"type":"object","properties":{"required":{"type":"string","pattern":"^[0-9]+(\\.[0-9]+)?$","description":"Required trading volume."}},"required":["required"],"description":"Required trading volume details for activation."}},"required":["stage","data"]}],"description":"Current state of the referrer."},"rewardHistory":{"type":"array","items":{"type":"object","properties":{"earned":{"type":"string","pattern":"^[0-9]+(\\.[0-9]+)?$","description":"Amount of earned rewards."},"vlm":{"type":"string","pattern":"^[0-9]+(\\.[0-9]+)?$","description":"Traded volume at the time of reward."},"referralVlm":{"type":"string","pattern":"^[0-9]+(\\.[0-9]+)?$","description":"Traded volume via referrals."},"time":{"type":"integer","minimum":0,"description":"Timestamp when the reward was earned (in ms since epoch)."}},"required":["earned","vlm","referralVlm","time"],"description":"Referral reward entry."},"description":"History of referral rewards."},"tokenToState":{"type":"array","items":{"type":"array","items":[{"type":"integer","minimum":0},{"type":"object","properties":{"cumVlm":{"type":"string","pattern":"^[0-9]+(\\.[0-9]+)?$","description":"Cumulative traded volume."},"unclaimedRewards":{"type":"string","pattern":"^[0-9]+(\\.[0-9]+)?$","description":"Rewards earned but not yet claimed."},"claimedRewards":{"type":"string","pattern":"^[0-9]+(\\.[0-9]+)?$","description":"Rewards that have been claimed."},"builderRewards":{"type":"string","pattern":"^[0-9]+(\\.[0-9]+)?$","description":"Builder reward amount."}},"required":["cumVlm","unclaimedRewards","claimedRewards","builderRewards"]}],"minItems":2,"description":"Tuple of token ID and its referral reward state."},"description":"Mapping of token IDs to referral reward states."}},"required":["referredBy","cumVlm","unclaimedRewards","claimedRewards","builderRewards","referrerState","rewardHistory","tokenToState"],"description":"Referral details for a user."}}}},"422":{"description":"Failed to deserialize the JSON body into the target type","content":{"text/plain":{"schema":{"type":"string"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"null"}}}}}}}}}
```
