Referral Data APIs
All referral endpoints require authentication. Include the session cookie from API Key Login or Wallet Login in every request.
List Epochs
Returns all epochs where start_time <= now, ordered by epoch ascending.
GET /api/v1/referral/epochs
No request parameters.
Response
{
"epochs": [
{
"epoch": 1,
"start_time": "2025-01-01T00:00:00Z",
"end_time": "2025-01-07T23:59:59Z"
},
{
"epoch": 2,
"start_time": "2025-01-08T00:00:00Z",
"end_time": "2025-01-14T23:59:59Z"
}
]
}
| Field |
Type |
Description |
epochs |
array |
List of epochs up to the current time |
epochs[].epoch |
int |
Epoch number |
epochs[].start_time |
string (ISO 8601) |
Start of the epoch |
epochs[].end_time |
string (ISO 8601) |
End of the epoch |
Get Point Summary
Returns the total points and community referral points earned by the authenticated account, optionally filtered to a range of epochs.
GET /api/v1/referral/points
Query Parameters
| Parameter |
Type |
Required |
Description |
from_epoch |
int32 |
No |
Start of epoch range (inclusive). 0 or omitted means no lower bound. |
to_epoch |
int32 |
No |
End of epoch range (inclusive). 0 or omitted means no upper bound. Must be >= from_epoch when both are set. |
Omitting or setting either parameter to 0 removes that bound, returning all epochs in that direction.
Response
{
"total_points": 1500.5,
"community_referral_points": 320.25
}
| Field |
Type |
Description |
total_points |
float64 |
Total points earned by the account |
community_referral_points |
float64 |
Points earned specifically from community referrals |
Errors
| HTTP Status |
Description |
400 |
to_epoch < from_epoch when both are non-zero |
401 |
Missing or invalid session cookie |
Get Referral Data
Returns paginated direct referral data for accounts referred by the authenticated account, optionally filtered to a range of epochs. By default, referred accounts with no trading activity may not appear in the results. Set include_all_referrals to true to include all current referrals regardless of activity.
GET /api/v1/referral/data
Query Parameters
| Parameter |
Type |
Required |
Description |
from_epoch |
int32 |
No |
Start of epoch range (inclusive). 0 or omitted means no lower bound. |
to_epoch |
int32 |
No |
End of epoch range (inclusive). 0 or omitted means no upper bound. Must be >= from_epoch when both are set. |
page_number |
int32 |
No |
Page number (1-indexed). Defaults to 1. |
page_size |
int32 |
No |
Number of results per page. Defaults to 100. |
include_all_referrals |
bool |
No |
When true, all current direct referrals are included regardless of trading activity. Accounts without attributed performance data in the requested epoch range will show zero values. Defaults to false. |
Response
{
"referrals": [
{
"account_id": "ACC:1234abcd",
"username": "trader_one",
"funding_account_address": "0xAbCd1234...",
"total_trading_volume": 50000.0,
"total_trading_fee": 125.0,
"total_eligible_trading_fee": 62.5,
"earning_from_referral": 31.25,
"cashback_earning": 10.0
}
],
"total": 42,
"page_number": 1,
"page_size": 20,
"total_trading_volume": 150000.0
}
| Field |
Type |
Description |
referrals |
array |
List of referred accounts for the requested page |
referrals[].account_id |
string |
Account ID of the referred user |
referrals[].username |
string |
Username of the referred user |
referrals[].funding_account_address |
string |
EVM wallet address of the referred user's funding account |
referrals[].total_trading_volume |
float64 |
Total trading volume generated by the referred account |
referrals[].total_trading_fee |
float64 |
Total trading fees paid by the referred account |
referrals[].total_eligible_trading_fee |
float64 |
Total trading fees paid by the referred account that is eligible for commission calculation after discounting maker fee rebates |
referrals[].earning_from_referral |
float64 |
Referral earnings credited to the referrer, calculated as a share of the generated fees eligible for commission |
referrals[].cashback_earning |
float64 |
Cashback earnings credited to the referred account |
total |
int64 |
Total number of referred accounts matching the filter |
page_number |
int32 |
Current page number |
page_size |
int32 |
Number of results per page |
total_trading_volume |
float64 |
Total trading volume of the authenticated (referrer) account, scoped by the requested epoch range |
Errors
| HTTP Status |
Description |
400 |
to_epoch < from_epoch when both are non-zero |
401 |
Missing or invalid session cookie |
Get Indirect Referral Data
Returns paginated indirect (L2) referral data for the authenticated account. Indirect referrals are accounts referred by the authenticated account's direct referrals, optionally filtered to a range of epochs. By default, referred accounts with no trading activity may not appear in the results. Set include_all_referrals to true to include all current referrals regardless of activity.
GET /api/v1/referral/indirect_data
Query Parameters
| Parameter |
Type |
Required |
Description |
from_epoch |
int32 |
No |
Start of epoch range (inclusive). 0 or omitted means no lower bound. |
to_epoch |
int32 |
No |
End of epoch range (inclusive). 0 or omitted means no upper bound. Must be >= from_epoch when both are set. |
page_number |
int32 |
No |
Page number (1-indexed). Defaults to 1. |
page_size |
int32 |
No |
Number of results per page. Defaults to 100. |
include_all_referrals |
bool |
No |
When true, all current indirect referrals are included regardless of trading activity. Accounts without attributed performance data in the requested epoch range will show zero values. Defaults to false. |
Response
{
"referrals": [
{
"account_id": "ACC:5678efgh",
"username": "indirect_trader",
"funding_account_address": "0xEfGh5678...",
"total_trading_volume": 25000.0,
"total_trading_fee": 62.5,
"total_eligible_trading_fee": 31.25,
"earning_from_referral": 15.625
}
],
"total": 10,
"page_number": 1,
"page_size": 20
}
| Field |
Type |
Description |
referrals |
array |
List of indirect referred accounts for the requested page |
referrals[].account_id |
string |
Account ID of the indirect referred user |
referrals[].username |
string |
Username of the indirect referred user |
referrals[].funding_account_address |
string |
EVM wallet address of the indirect referred user's funding account |
referrals[].total_trading_volume |
float64 |
Total trading volume generated by the indirect referred account |
referrals[].total_trading_fee |
float64 |
Total trading fees paid by the indirect referred account |
referrals[].total_eligible_trading_fee |
float64 |
Total trading fees eligible for commission calculation after discounting maker fee rebates |
referrals[].earning_from_referral |
float64 |
Referral earnings from the indirect referral, calculated as a share of the generated fees eligible for commission |
total |
int64 |
Total number of indirect referred accounts matching the filter |
page_number |
int32 |
Current page number |
page_size |
int32 |
Number of results per page |
Errors
| HTTP Status |
Description |
400 |
to_epoch < from_epoch when both are non-zero |
401 |
Missing or invalid session cookie |