TraderCodeService

service TraderCodeService {
  rpc GetMyTraderCode(GetMyTraderCodeRequest) returns (TraderCodeResponse);
  rpc SetTraderCode(SetTraderCodeRequest) returns (TraderCodeResponse);
  rpc ClearTraderCode(ClearTraderCodeRequest) returns (TraderCodeResponse);
  rpc CheckTraderCodeAvailability(CheckTraderCodeAvailabilityRequest) returns (CheckTraderCodeAvailabilityResponse);
  rpc GetTraderCodeInfo(GetTraderCodeInfoRequest) returns (GetTraderCodeInfoResponse);
  rpc GetRewardsBalance(GetRewardsBalanceRequest) returns (GetRewardsBalanceResponse);
  rpc TransferRewards(TransferRewardsRequest) returns (TransferRewardsResponse);
  rpc GetMyReferralPosition(GetMyReferralPositionRequest) returns (GetMyReferralPositionResponse);
  rpc GetMyReferralDownline(GetMyReferralDownlineRequest) returns (GetMyReferralDownlineResponse);
  rpc GetMyReferralTree(GetMyReferralTreeRequest) returns (GetMyReferralTreeResponse);
}

​

Notes

• GetMyTraderCode requires authentication. It is idempotent and never returns NOT_FOUND — the code row is created on demand for the authenticated wallet.
• GetTraderCodeInfo is public (no auth). It accepts a bare wallet address or the Monaco - <address> display form. Returns NOT_FOUND when the code does not resolve to a known wallet.
• GetRewardsBalance returns an empty balances list when no rewards have been earned yet. available values are in raw atomic units.
• TransferRewards moves the specified amount from the caller’s rewards bucket into the calling application’s trading balance. The transfer is ledger-only — no on-chain transaction. Returns ALREADY_EXISTS (HTTP 409 over REST) when the rewards balance is insufficient. Each call spends the per-user movement budget withdrawals and collateral transfers share, whatever the balance; RESOURCE_EXHAUSTED when that budget is enforced and spent.
• Monaco configures how many referral levels TraderCodes rewards (1 to 10) and a rate per level; rates may change over time and apply to future fills only. The rate_applied on each reward row is captured at fill time. Reward level is 1 for the direct referrer, 2 for the referrer’s referrer, and so on (at most 10).
• GetMyReferralPosition, GetMyReferralDownline, and GetMyReferralTree are authenticated and self-scoped: identity comes only from the session, never a request id, so a caller can only ever read their own referral chain. All three map every other user to their public wallet address (with a display custom-handle-or-wallet variant), never an internal id.
• GetMyReferralPosition returns your upline — the chain above you, nearest first: L1 (your direct referrer), L2, and so on, with at most as many entries as TraderCodes rewards levels (at most 10) — and the L1 wallet again as referrer (both empty when you were not referred), your all-time total_earned, and your most recent reward rows (up to the 100 newest; total_earned stays the complete aggregate).
• GetMyReferralDownline returns one page of earnings_by_source across every reward level, ordered by each source account’s total, largest first (a wallet’s per-application rows are merged within a page at the first row’s position); your L1 direct-referee roster (including referees who have not traded yet, shown with 0 earned; showing up to the 500 most recent effective referees (after per-wallet dedupe), drawn from a bounded scan so a very large history may yield an incomplete roster, while the earnings views stay complete); and a per-level summary. Page with page_size (1–500, default 100) and page_token (the opaque next_page_token from the previous response; next_page_token is empty when no rows remain). A request without paging fields returns only the first page, not every row — follow next_page_token until it is empty. Rows of a wallet that traded through several applications are merged within a page, but that wallet can appear again on a later page. summary covers every level and source regardless of the page: summary.by_level lists { level, earned } (raw atomic units) in ascending level order, one entry per level with earnings, including levels deeper than TraderCodes rewards today. summary.level1_earned, level2_earned, and level3_earned are deprecated (levels 1–3 only); use by_level.
• GetMyReferralTree returns one level of your downline per call: with no parent, your L1 referees; with parent set to one of your referees above the deepest rewarded level, that wallet’s referees. Each ReferralTreeNode carries level, parent, referred_at, referee_count (expandable when above 0; always 0 at the deepest rewarded level), and total_earned from that wallet’s own trades. Pages hold up to 200 nodes (page_size, default 50) with a next_page_token that is only valid for the same parent. Each wallet appears once, under the referrer that earns from it. level ranges 1–10 and the response’s parent_level 0–9. A parent that is not you or one of your referees above the deepest rewarded level returns NOT_FOUND; a malformed parent, page_size, or page_token returns INVALID_ARGUMENT.
• The referral reads share the standard authenticated-read error set: UNAUTHENTICATED when the session is missing or invalid, RESOURCE_EXHAUSTED when the account’s read budget is exhausted (retry after the interval in the RetryInfo detail), and INTERNAL on a server error.