TraderCodeService

service TraderCodeService {
  rpc GetMyTraderCode(GetMyTraderCodeRequest) returns (TraderCodeResponse);
  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);
}

​

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 FAILED_PRECONDITION when the rewards balance is insufficient.
• Reward rates are configured via feature flags and may change over time. The rate_applied on each reward event is captured at fill time and stored in the audit log.
• GetMyReferralPosition and GetMyReferralDownline 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. Both map every other user to their public wallet address (with a display custom-handle-or-wallet variant), never an internal id.
• GetMyReferralPosition returns your direct (L1) referrer only (referrer is 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 earnings_by_source across all three reward levels (L1/L2/L3), 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 unbounded), and a per-level summary.
• Both 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.