> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chainstack.com/llms.txt
> Use this file to discover all available pages before exploring further.
# referral | Hyperliquid info
> The info endpoint with type: "referral" retrieves comprehensive referral information for a specific user on the Hyperliquid exchange.
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. See [Hyperliquid methods](/docs/hyperliquid-methods) for the full availability breakdown.
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.
The example curl call is for the user `0x1442ad477ded1b0028b57621aa7b6f7eadb8f568` that used the AXIOM referral code `0x1cc34f6af34653c515b47a83e1de70ba9b0cda1f`. Here's an example `setReferrer` transaction [0xaa79d3a0073a73925828041e25e24a012300149a6f622a0727287dafe158fff5](https://hypurrscan.io/tx/0xaa79d3a0073a73925828041e25e24a012300149a6f622a0727287dafe158fff5).
## 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 Shell theme={"system"}
curl -X POST \
-H "Content-Type: application/json" \
-d '{"type": "referral", "user": "0x1442ad477ded1b0028b57621aa7b6f7eadb8f568"}' \
https://api.hyperliquid.xyz/info
```
```python Python (hyperliquid-python-sdk) theme={"system"}
from hyperliquid.info import Info
from hyperliquid.utils import constants
info = Info(constants.MAINNET_API_URL, skip_ws=True)
# type: "referral"
referral = info.query_referral_state("0x1442ad477ded1b0028b57621aa7b6f7eadb8f568")
print(referral)
```
```typescript TypeScript (@nktkas/hyperliquid) theme={"system"}
import { HttpTransport, InfoClient } from "@nktkas/hyperliquid";
const transport = new HttpTransport();
const info = new InfoClient({ transport });
// type: "referral"
const referral = await info.referral({
user: "0x1442ad477ded1b0028b57621aa7b6f7eadb8f568",
});
console.log(referral);
```
## Example response
```json theme={"system"}
{
"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.
## OpenAPI
````yaml openapi/hyperliquid_node_api/hypercore_info/info_referral.json post /info
openapi: 3.0.0
info:
title: Hyperliquid Node API - Referral
version: 1.0.0
servers:
- url: https://api.hyperliquid.xyz
security: []
paths:
/info:
post:
summary: Query a user's referral information
description: >-
Retrieve comprehensive referral information for a specific user,
including referrer details, referral rewards, volume metrics, and
referrer state with referred users data.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- type
- user
properties:
type:
type: string
enum:
- referral
default: referral
description: >-
The request type. Must be 'referral' to retrieve referral
information.
user:
type: string
pattern: ^0x[a-fA-F0-9]{40}$
default: '0x1442ad477ded1b0028b57621aa7b6f7eadb8f568'
description: >-
Address in 42-character hexadecimal format; e.g.
0x0000000000000000000000000000000000000000.
example:
type: referral
user: '0x1442ad477ded1b0028b57621aa7b6f7eadb8f568'
responses:
'200':
description: Successful response with referral information
content:
application/json:
schema:
type: object
properties:
referredBy:
type: object
description: Information about who referred this user
properties:
referrer:
type: string
description: Address of the user who made the referral
code:
type: string
description: Referral code used
cumVlm:
type: string
description: Cumulative volume traded by this user
unclaimedRewards:
type: string
description: Amount of unclaimed referral rewards
claimedRewards:
type: string
description: Amount of claimed referral rewards
builderRewards:
type: string
description: Builder rewards earned
referrerState:
type: object
description: State information if this user is a referrer
properties:
stage:
type: string
description: Current stage of the referrer (e.g., 'ready')
data:
type: object
properties:
code:
type: string
description: This user's referral code
referralStates:
type: array
description: List of users referred by this user
items:
type: object
properties:
cumVlm:
type: string
description: >-
Cumulative volume traded by the referred
user
cumRewardedFeesSinceReferred:
type: string
description: >-
Total fees that generated rewards since
referral
cumFeesRewardedToReferrer:
type: string
description: >-
Total fees rewarded to the referrer from
this user
timeJoined:
type: integer
format: int64
description: Timestamp when the user joined via referral
user:
type: string
description: Address of the referred user
rewardHistory:
type: array
description: >-
Legacy reward history (now returned in
nonFundingLedgerUpdate)
example:
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: []
````