TraderCodes

TraderCodes is the PitPass referral program: referrers earn a share of the protocol fee on their referees’ trades. Earn covers the program; this page covers integration.

Surface Map

Surface	Use
REST	`GET /api/v1/tradercodes/codes/me`, `GET /api/v1/tradercodes/codes/{code}`, `PUT /api/v1/tradercodes/codes/me/custom`, `DELETE /api/v1/tradercodes/codes/me/custom`, `GET /api/v1/tradercodes/codes/available`, `GET /api/v1/tradercodes/rewards/balance`, `POST /api/v1/tradercodes/rewards/transfer`, `GET /api/v1/tradercodes/referrals/me`, `GET /api/v1/tradercodes/referrals/me/downline`, `GET /api/v1/tradercodes/referrals/me/tree`
TypeScript SDK	`sdk.tradercodes.getMyTraderCode()`, `sdk.tradercodes.getTraderCodeInfo(code)`, `sdk.tradercodes.setTraderCode(code)`, `sdk.tradercodes.clearTraderCode()`, `sdk.tradercodes.checkTraderCodeAvailability(code)`, `sdk.tradercodes.getRewardsBalance()`, `sdk.tradercodes.transferRewards(params)`, `sdk.tradercodes.getMyReferralPosition()`, `sdk.tradercodes.getMyReferralDownline(params?)`, `sdk.tradercodes.getMyReferralTree(params?)`
React SDK	`useMyTraderCode()`, `useSetTraderCode()`, `useClearTraderCode()`, `useTraderCodeAvailability()`, `useRewardsBalance()`, `useTransferRewards()`, `useMyReferralPosition()`, `useMyReferralDownline()`, `useMyReferralTree()`, or any core SDK method through `useMonacoSDK()`
WebSocket	None
gRPC	`monaco.api.tradercodes.TraderCodeService`

Concepts

Term	Meaning
TraderCode	Default code derived from the wallet address (`Monaco - <address>`). Globally unique, valid on every Monaco app, permanent.
Custom handle	Optional vanity code shown instead of the default. The chain keys on the wallet, so changing or clearing it never affects rewards or referrals.
Referral chain	L1 is your direct referrer, L2 theirs, and so on, up to 10 rewarded levels. A trade pays the levels and rates of the client application it was placed through.
Rewards bucket	Per-user, app-agnostic balance where rewards land, separate from trading balances.

Forward the referral code (for example from a ?ref=CODE URL parameter) as referralCode on auth verify. Use sdk.auth.authenticate(clientId, code); sdk.login does not forward a referral code.

// Optional: confirm the code resolves before showing a confirmation. 404 when it does not.
const info = await sdk.tradercodes.getTraderCodeInfo(code); // info.code is the normalized wallet address

await sdk.auth.authenticate("your-client-id", code);

curl -X POST "https://apimonaco.xyz/api/v1/auth/verify" \
  -H "Content-Type: application/json" \
  -d '{ "sessionPublicKey": "...", "signature": "...", "referralCode": "0xabc..." }'

A referral never blocks sign-in; an invalid code or self-referral is silently ignored.
A referral is recorded once, at first sign-up. A wallet keeps its first referrer: a later sign-up (on any client application) with a different referrer’s code records nothing, and the verify response reports referralNotAppliedReason: REFERRAL_NOT_APPLIED_REASON_ALREADY_REFERRED. A later sign-up with the same referrer’s code is recorded as usual.

Show a User’s TraderCode

getMyTraderCode never returns 404 for a signed-in wallet. Render display; it reflects any custom handle. Embed code in referral links (?ref=<code>).

const { code, display, isCustom } = await sdk.tradercodes.getMyTraderCode();

{
  "code": "0xabc123...",
  "createdAt": "2026-07-01T00:00:00Z",
  "customCode": "",
  "isCustom": false,
  "display": "Monaco - 0xabc123..."
}

With a custom handle, customCode holds it as entered, isCustom is true, and display is the handle.

Claim a Custom Handle

Rules: letter-first, [A-Za-z0-9_], 5–20 characters, casing preserved, unique case-insensitively.

// Public, no auth. Debounce for live feedback while the user types.
const { available, reason } = await sdk.tradercodes.checkTraderCodeAvailability("acePilot");
// reason ∈ "taken" | "too_short" | "too_long" | "reserved" | "invalid_char" | "looks_like_address"

const { display, isCustom } = await sdk.tradercodes.setTraderCode("acePilot"); // claim or edit
await sdk.tradercodes.clearTraderCode(); // revert to the default

curl -X PUT "https://apimonaco.xyz/api/v1/tradercodes/codes/me/custom" \
  -H "Content-Type: application/json" \
  -H "X-Monaco-PublicKey: $MONACO_SESSION_PUBLIC_KEY" \
  -H "X-Monaco-Timestamp: $MONACO_TIMESTAMP" \
  -H "X-Monaco-Signature: $MONACO_SIGNATURE" \
  -d '{ "code": "acePilot" }'

Status	`setTraderCode` / `clearTraderCode`
`409`	Handle taken, or a recently freed handle still in cooldown (set only)
`422`	Validation failed, with a reason code (set only)
`429`	Too many edits in the rolling hour; set and clear share the limit
`403`	Custom handles are disabled

The availability check (GET /api/v1/tradercodes/codes/available?code=...) is advisory and rate-limited (429 past the allowance). setTraderCode is the authoritative gate.

Read Referral State

Authenticated; return only your own chain. Other users appear as wallet address plus display (custom handle when claimed), never an internal id.

Method	Returns
`getMyReferralPosition()`	`upline` (chain above you, nearest first, one entry per level this client pays, max 10; empty if unreferred or the client pays no levels), `referrer` (`""` if none), all-time `totalEarned`, and the 100 newest reward rows.
`getMyReferralDownline(params?)`	Paged `earningsBySource` (who pays you, all levels, largest source total first); `directReferees` (L1 roster incl. non-traders, the 500 most recent after per-wallet dedupe, from a bounded scan, so a very large history may be incomplete; earnings stay complete); per-level `summary`.
`getMyReferralTree(params?)`	One level per call: no `parent` lists your L1; a referee’s wallet as `parent` lists its referees, down to the deepest level any client rewards.

Downline paging. Pass pageSize (1–500, default 100) and pageToken (the previous nextPageToken) as SDK params or query parameters. Without them you get only the first page; repeat until nextPageToken is "". A wallet that traded through several applications is merged within a page at its first part’s position, so a merged row can sit below a smaller one and the wallet can reappear on a later page. summary always covers every level and source: summary.byLevel lists { level, earned } (raw atomic units), ascending, for each level with earnings, including levels deeper than currently rewarded. summary.level1Earned, level2Earned, and level3Earned are deprecated (levels 1–3 only); use byLevel.

const first = await sdk.tradercodes.getMyReferralDownline({ pageSize: 500 });
const rows = [...first.earningsBySource];
let pageToken = first.nextPageToken;
while (pageToken) {
  const page = await sdk.tradercodes.getMyReferralDownline({ pageSize: 500, pageToken });
  rows.push(...page.earningsBySource);
  pageToken = page.nextPageToken;
}

Tree nodes. Each node carries level, parent, referredAt, refereeCount (expandable when above 0; always 0 at the deepest rewarded level), and totalEarned (what you earned from that wallet’s own trades). Pages hold up to 200 nodes (default 50) with a nextPageToken. Your L1 referees are always listed, and each wallet appears once, under the referrer that earns from it. A parent that is not you or one of your referees above the deepest rewarded level returns 404.

Check Rewards Balance

Returns one entry per reward token; an empty list when nothing is earned yet. available is in raw atomic units: divide by the token’s decimals (10^6 for USDC).

const { balances } = await sdk.tradercodes.getRewardsBalance();

{ "balances": [{ "token": "0xusdc...", "available": "1200000" }] }

Transfer Rewards to a Trading Balance

Moves rewards into the authenticated application’s trading balance. Ledger-only: no on-chain transaction or gas, tradeable immediately. amount: positive integer string, raw atomic units.

const { rewardsBalance, tradingBalance } = await sdk.tradercodes.transferRewards({
  token: "0xusdc...",
  amount: "1200000",
});

curl -X POST "https://apimonaco.xyz/api/v1/tradercodes/rewards/transfer" \
  -H "Content-Type: application/json" \
  -H "X-Monaco-PublicKey: $MONACO_SESSION_PUBLIC_KEY" \
  -H "X-Monaco-Timestamp: $MONACO_TIMESTAMP" \
  -H "X-Monaco-Signature: $MONACO_SIGNATURE" \
  -d '{ "token": "0xusdc...", "amount": "1200000" }'

Returns the remaining rewardsBalance and the new tradingBalance for the token.
409: amount exceeds the available rewards balance; refresh and show the current amount.
Each call spends the per-user movement budget shared with withdrawals and collateral transfers, whatever the rewards balance; past it the answer is 429 with Retry-After once that budget is enforced.

Reward Rates

Monaco configures the rewarded depth (1 to 10 levels) and a rate per level, optionally per client application.

Every level takes its rate of the same reward base for the fill; levels do not compound. All rates together never exceed 100% of that base.
Rewards are computed at fill time and credited instantly. Each reward row records the rateApplied.
Levels beyond the end of a shorter chain are not paid.
Configuration changes apply to future fills only. Rewards earned at a level deeper than the current depth stay readable in reward history, earningsBySource, and summary.byLevel.

Auth: full sign-in flow
TypeScript TraderCodes SDK: method signatures
REST schemas: Get your TraderCode, Look up a TraderCode, Get rewards balance, Transfer rewards

Learn

Build

Libraries

APIs

Resources

Surface Map

Concepts

Show a User’s TraderCode

Claim a Custom Handle

Read Referral State

Check Rewards Balance

Transfer Rewards to a Trading Balance

Reward Rates

​Surface Map

​Concepts

​Capture a Referral at Sign-In

​Show a User’s TraderCode

​Claim a Custom Handle

​Read Referral State

​Check Rewards Balance

​Transfer Rewards to a Trading Balance

​Reward Rates

​Related References

Surface Map

Concepts

Capture a Referral at Sign-In

Show a User’s TraderCode

Claim a Custom Handle

Read Referral State

Check Rewards Balance

Transfer Rewards to a Trading Balance

Reward Rates

Related References