Sync

Referrals (on-chain fee)

Fee referrals (on-chain)

Fee referral (on-chain). The referred wallet sends setReferrer(referrer) to the BASIS referral registry once, as its own transaction. It is permanent. The referrer cannot be yourself or a wallet you referred, and a protocol wallet earns nothing as a referrer. From then on the referred wallet pays 10% less base fee (0.54% instead of 0.60% today), its referrer receives 15% of the base fee of its trades and bets, and that referrer's own referrer receives 5%, paid at once in the pair asset of the token's main. Nothing is paid on loans or leverage opens and nothing is retroactive. It is independent of the legacy points referral.

Set it by sending setReferrer(referrer) to the referral registry and posting the transaction hash to POST /api/v1/sync.

GET

/api/v1/me/referrals

Returns your referral overview (any wallet: GET /api/v1/wallet/{address}/referrals with an API key, ?depth=1..5 and paged referrals). The top-level fields are the legacy referral: who referred you and the wallets you referred, oldest first. Points were removed at the relaunch, so there is no tier or rank. `onchain` is the fee referral: your on-chain referrer, your referral tree to level 2, and earnings per pair asset and level. Optional query `from`, `to` (ISO date, or unix milliseconds) bound the on-chain figures.

Auth: Session or API Key

Response

{
  "referrer": {
    "wallet": "0x...",
    "username": "alice"
  },
  "directCount": 5,
  "indirectCount": 12,
  "referrals": [
    {
      "wallet": "0x...",
      "username": "bob",
      "layer": 1,
      "joinedAt": "2026-01-15T12:00:00.000Z"
    }
  ],
  "onchain": {
    "referrer": "0x...",
    "directCount": 3,
    "indirectCount": 1,
    "earnings": [
      { "pairAsset": "0x...", "pairDecimals": 6, "level": 1, "amount": "1500000", "amountUsdE18": "1500000000000000000", "wallets": 3 }
    ],
    "referrals": [
      {
        "wallet": "0x...",
        "referrer": "0x...",
        "level": 1,
        "earned": [
          { "pairAsset": "0x...", "pairDecimals": 6, "amount": "900000", "amountL1": "900000", "amountL2": "0", "amountUsdE18": "900000000000000000" }
        ],
        "feesGenerated": [
          { "pairAsset": "0x...", "pairDecimals": 6, "amount": "6000000", "amountUsdE18": "6000000000000000000" }
        ]
      }
    ],
    "redirected": [
      { "pairAsset": "0x...", "pairDecimals": 6, "symbol": "USDG", "amount": "300000", "amountUsdE18": "300000000000000000", "usdSource": "fixed", "usdCovered": 1, "n": 1 }
    ],
    "redirectedTotal": { "totalUsdE18": "300000000000000000", "usdCovered": 1, "n": 1, "usdSources": ["fixed"] },
    "redirects": [
      { "token": "0x...", "pairAsset": "0x...", "pairDecimals": 6, "symbol": "USDG", "amount": "300000", "amountUsdE18": "300000000000000000", "usdSource": "fixed", "sentTo": "platform", "txHash": "0x...", "blockNumber": 12345678, "logIndex": 9, "time": 1760000000 }
    ],
    "redirectsTruncated": false
  }
}

referrer is null if you have no referrer. layer is 1 for direct, 2 for indirect. Oldest first. These are the legacy referral. onchain is the fee referral (AReferrals.setReferrer, the referral registry at caREFERRALS; TAXES only reads it and pays the fees), read from synced events with no RPC; it is null when TAXES or the registry is not deployed. Amounts are decimal strings in the pair asset's units (pairDecimals); amountUsdE18 is null when the USD price is unknown.

redirected is kept apart from earnings: a referral payout this wallet could not receive (its wallet cannot take the pair asset), which TAXES sent to the protocol instead (PayoutRedirected). It was not earned. Per pair asset over the window, with the USD at each event; redirectedTotal is the USD total (null unless every row is priced). redirects lists the newest 100 records (redirectsTruncated when there are more); every record is also a referral_redirected row of GET /api/v1/wallet/{address}/activity?types=referral.

200 Referral overview returned401 Not authenticated

GET

/api/v1/profile/{wallet}/referrals

Returns public referral counts for any wallet. The top-level fields are the legacy points referral (frozen: points were removed at the relaunch). `onchain` holds the same counts for the on-chain fee referral (AReferrals.setReferrer, the registry at caREFERRALS), null when TAXES or the registry is not deployed. Does not expose wallet addresses or earnings.

Auth: API Key

Response

{
  "wallet": "0x...",
  "hasReferrer": true,
  "directReferrals": 5,
  "indirectReferrals": 12,
  "totalReferrals": 17,
  "onchain": {
    "hasReferrer": true,
    "directReferrals": 3,
    "indirectReferrals": 1,
    "totalReferrals": 4
  }
}

200 Public referral counts returned401 Missing or invalid API key