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/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

{
  "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 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 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 here.