> For the complete documentation index, see [llms.txt](https://basedapp.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://basedapp.gitbook.io/docs/integrations/builder-on-builder-program/builder-api-access.md). # 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. {% hint style="warning" %} 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. {% endhint %} ## 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/referrals ``` ### Authentication All API requests must include a valid API key in the request headers. #### Header Required ``` x-api-key: YOUR_API_KEY ``` #### Authentication Error Response ```json { "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 ```bash 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 ```json { "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 ```bash curl -X GET "https://app.based.one/api/builders/referrals/volume_30d/ABC123" \ -H "x-api-key: YOUR_API_KEY" ``` #### Sample Response ```json { "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 query * `address` (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 to `true` to get all-time data instead of a rolling window (default: `false`) #### Sample Request ```bash curl -X GET "https://basedapp.io/api/builders/referrals/ABC123/user/0xabcdef1234567890abcdef1234567890abcdef12?days=7" \ -H "x-api-key: YOUR_API_KEY" ``` #### Sample Response ```json { "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 ```json { "error": "Invalid or missing API key" } ``` #### 400 Bad Request ```json { "error": "Referral code is required" } ``` #### 403 Forbidden ```json { "error": "User is not a referral under this referral code" } ``` #### 404 Not Found ```json { "error": "Referral code not found" } ``` #### 500 Internal Server Error ```json { "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 x 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 [here](/docs/others/contact-us.md).