Builder API access
Methodology
We use actual Hyperliquid builder trade data published by Hyperliquid, which is subject to a 48-hour time lag.
To provide near real-time accuracy, we fill in the most recent 48-hour gap using our own live trade tracking system, which may carry a small margin of error.
Important: When calculating commissions, we do not use the real-time (rolling) data. Only confirmed on-chain data is used once it becomes available through Hyperliquid’s official stream.
Builders Referrals API Documentation
This API provides access to referral data and trading volume information for specific referral codes. All endpoints are read-only and require API key authentication.
Base URL
https://app.based.one/api/builders/referralsAuthentication
All API requests must include a valid API key in the request headers.
Header Required
x-api-key: YOUR_API_KEYAuthentication Error Response
{
"error": "Invalid or missing API key"
}1. Get All Referrals by Code
Retrieve a complete list of all referrals (tier 1, 2, and 3) under a specific referral code with their trading performance and commission data.
Endpoint
GET /api/builders/referrals/[code]Parameters
code(path parameter, required): The referral code to query
Query Parameters
sortBy(optional): Sort field -registrationDate,totalTraded,commissionEarned(default:registrationDate)sortDirection(optional): Sort direction -asc,desc(default:desc)tier(optional): Filter by tier -all,tier1,tier2,tier3(default:all)
Sample Request
curl -X GET "https://app.based.one/api/builders/referrals/ABC123?sortBy=totalTraded&sortDirection=desc&tier=tier1" \
-H "x-api-key: YOUR_API_KEY"Sample Response
{
"success": true,
"data": {
"referralCode": "ABC123",
"referralOwner": {
"username": "trader_pro",
"address": "0x1234567890abcdef1234567890abcdef12345678"
},
"referrals": [
{
"address": "0xabcdef1234567890abcdef1234567890abcdef12",
"registrationDate": "2024-01-15T10:30:00.000Z",
"totalTraded": 15750.25,
"commissionEarned": 945.02,
"builderFees": 1575.03,
"tier": 1,
"commissionRate": 60
},
{
"address": "0x9876543210fedcba9876543210fedcba98765432",
"registrationDate": "2024-02-01T14:20:00.000Z",
"totalTraded": 8420.50,
"commissionEarned": 101.05,
"builderFees": 842.05,
"tier": 2,
"commissionRate": 12
}
],
"summary": {
"tier1Count": 15,
"tier2Count": 8,
"tier3Count": 3,
"totalTier1Commission": 2450.75,
"totalTier2Commission": 245.30,
"totalTier3Commission": 48.15,
"commissionRates": {
"tier1": 60,
"tier2": 12,
"tier3": 4
}
}
}
}2. Get 30-Day Rolling Volume by Code
Retrieve referral data showing only the last 30 days of trading volume and commission earnings.
Endpoint
GET /api/builders/referrals/volume_30d/[code]Parameters
code(path parameter, required): The referral code to query
Query Parameters
sortBy(optional): Sort field -registrationDate,totalTraded,commissionEarned(default:registrationDate)sortDirection(optional): Sort direction -asc,desc(default:desc)tier(optional): Filter by tier -all,tier1,tier2,tier3(default:all)
Sample Request
curl -X GET "https://app.based.one/api/builders/referrals/volume_30d/ABC123" \
-H "x-api-key: YOUR_API_KEY"Sample Response
{
"success": true,
"data": {
"referralCode": "ABC123",
"referralOwner": {
"username": "trader_pro",
"address": "0x1234567890abcdef1234567890abcdef12345678"
},
"period": {
"startDate": "2024-12-06T01:45:59.378Z",
"endDate": "2025-01-05T01:45:59.378Z",
"days": 30
},
"referrals": [
{
"address": "0xabcdef1234567890abcdef1234567890abcdef12",
"registrationDate": "2024-01-15T10:30:00.000Z",
"totalTraded": 5240.75,
"commissionEarned": 314.45,
"builderFees": 524.08,
"tier": 1,
"commissionRate": 60
}
],
"summary": {
"totalVolume": 12450.50,
"totalCommission": 745.25,
"tier1Count": 12,
"tier2Count": 5,
"tier3Count": 2,
"totalTier1Commission": 620.30,
"totalTier2Commission": 98.45,
"totalTier3Commission": 26.50,
"commissionRates": {
"tier1": 60,
"tier2": 12,
"tier3": 4
}
}
}
}3. Get Individual User Volume by Address
Retrieve detailed trading volume and commission data for a specific user address under a referral code, including trade history and asset breakdown.
Endpoint
GET /api/builders/referrals/[code]/user/[address]Parameters
code(path parameter, required): The referral code to queryaddress(path parameter, required): The wallet address of the specific user
Query Parameters
days(optional): Number of days to look back (default:30)includeAllTime(optional): Set totrueto get all-time data instead of rolling window (default:false)
Sample Request
curl -X GET "https://basedapp.io/api/builders/referrals/ABC123/user/0xabcdef1234567890abcdef1234567890abcdef12?days=7" \
-H "x-api-key: YOUR_API_KEY"Sample Response
{
"success": true,
"data": {
"referralCode": "ABC123",
"referralOwner": {
"username": "trader_pro",
"address": "0x1234567890abcdef1234567890abcdef12345678"
},
"user": {
"address": "0xabcdef1234567890abcdef1234567890abcdef12",
"registrationDate": "2024-01-15T10:30:00.000Z",
"tier": 1,
"commissionRate": 60
},
"period": {
"type": "rolling_days",
"days": 7,
"startDate": "2024-12-29T01:49:03.790Z",
"endDate": "2025-01-05T01:49:03.790Z"
},
"summary": {
"totalVolume": 2450.75,
"totalBuilderFees": 61.27,
"totalCommission": 36.76,
"tradeCount": 15,
"assetBreakdown": {
"BTC": {
"volume": 1500.50,
"builderFees": 37.51,
"commission": 22.51,
"tradeCount": 8
},
"ETH": {
"volume": 950.25,
"builderFees": 23.76,
"commission": 14.25,
"tradeCount": 7
}
}
},
"trades": [
{
"source": "TraderTrade",
"tradeTime": "2025-01-05T01:30:00.000Z",
"volume": 250.50,
"builderFee": 6.26,
"commissionEarned": 3.76,
"coin": "BTC",
"side": "B"
},
{
"source": "BuilderTrade",
"tradeTime": "2025-01-04T18:45:00.000Z",
"volume": 180.25,
"builderFee": 4.51,
"commissionEarned": 2.70,
"coin": "ETH",
"side": "S"
}
]
}
}Error Responses
All endpoints return consistent error responses:
401 Unauthorized
{
"error": "Invalid or missing API key"
}400 Bad Request
{
"error": "Referral code is required"
}403 Forbidden
{
"error": "User is not a referral under this referral code"
}404 Not Found
{
"error": "Referral code not found"
}500 Internal Server Error
{
"error": "An error occurred while fetching referrals"
}Data Definitions
Commission Rates
Tier 1 (Direct referrals): 60% of builder fees
Tier 2 (Sub-referrals): 12% of builder fees
Tier 3 (Sub-sub-referrals): 4% of builder fees
Data Sources
BuilderTrade: Historical trading data (cleaned, up to cutoff date)
TraderTrade: Recent trading data (real-time, from cutoff date onwards)
Volume Calculation
All volume figures represent the total USD value of trades (price × size) executed by the referral users within the specified time period.
Getting API Access
To obtain an API key for accessing these endpoints, please contact the development team. API keys are issued for legitimate business use cases.
Rate Limits
These endpoints currently have no rate limits, but reasonable usage is expected. For high-volume integrations, please contact support.
Support
For API support, API key requests, or questions, please contact the development team.
Last updated