> ## Documentation Index
> Fetch the complete documentation index at: https://docs.0xmonaco.com/llms.txt
> Use this file to discover all available pages before exploring further.

# TraderCodeService

> TraderCodes referral codes and rewards

Package: `monaco.api.tradercodes`

Source: `protos/api/tradercodes.proto`

<Note>
  `monaco.api.pitpass.TraderCodeService` (`protos/api/pitpass.proto`) is a deprecated alias of this service: the same RPCs and messages, served by the same handlers, so it returns identical responses. Use `monaco.api.tradercodes`.
</Note>

Use `TraderCodeService` to retrieve and validate TraderCodes, read your referral position, downline, and referral tree, read a user's rewards balance, and transfer earned rewards into a trading balance.

```protobuf theme={null}
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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.