TraderCodes

PitPass TraderCodes give every Monaco user a unique referral code tied to their wallet. When a referred user trades, the referrer earns a slice of the net protocol fee — up to three levels deep. Rewards land in an app-agnostic rewards bucket and can be moved into any trading balance with a single ledger-only call. Every wallet has a default code derived from its address, and a user can optionally claim a custom (vanity) handle — a human-readable code that is easier to share. Use TraderCodes to capture a referral at signup, display a user’s code for sharing, let users claim a custom handle, and let them check and move their earned rewards.

Surface Map

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

Concepts

TraderCode. Every wallet has a default code derived from its address, displayed by clients as Monaco - <address>. Codes are globally unique, work across every app on Monaco, and the default is permanent. Calling getMyTraderCode is idempotent — the code row is created on demand, so the endpoint never 404s for a signed-in wallet. Render the response’s display field rather than building the display string yourself; it already reflects a custom handle when one is set. Custom handle. A wallet can claim a custom (vanity) handle to use in place of the wallet-derived default: letter-first, [A-Za-z0-9_], 5–20 characters, stored exactly as entered (casing preserved) but unique case-insensitively. Claim or edit it with setTraderCode, drop it with clearTraderCode (reverting to the default), and preview a handle with the public checkTraderCodeAvailability. getMyTraderCode reports isCustom and the claimed customCode alongside the default code. The referral chain always keys on the wallet, so changing or clearing a handle never affects earned rewards or referral relationships. Referral chain. A referral relationship is recorded once at first signup. The chain is a directed graph: L1 is the direct referrer, L2 is their referrer, L3 is L2’s referrer. Each level earns a configured percentage of the net fee generated by the referred user’s trades. Reading referral state. Two self-scoped, authenticated reads back the referral UI. getMyReferralPosition() returns your direct (L1) referrer (referrer is "" when you were not referred), your all-time totalEarned, and recent reward rows (up to the 100 newest; totalEarned stays the complete aggregate) — use it for an “already referred” state and an earnings header. getMyReferralDownline() returns earningsBySource (who pays you, across L1/L2/L3), your L1 directReferees roster (including referees who have not traded yet, 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 — the earnings views stay unbounded), and a per-level summary. Both identify every other user by wallet address plus a display (their custom handle when claimed), never an internal id, and only ever return your own chain. Rewards bucket. Earned rewards land in a dedicated per-user rewards bucket that is separate from any application’s trading balance. The bucket is app-agnostic — a referrer earns rewards regardless of which app their referee trades on. To spend rewards, move them into a trading balance via transferRewards. Transfer. The transfer between rewards bucket and trading balance is ledger-only (Monaco operates a single shared vault). No on-chain transaction, no gas. Funds are tradeable immediately after the transfer.

Flow

Pass the referral code in the auth verify body. The code is silently ignored if it is invalid or if the user already exists, so it never blocks sign-in. The trading front-end captures ?ref=CODE from the URL and forwards it here.

Validate the code (optional)

Before showing the user a confirmation, call the public lookup to verify the code resolves.

const info = await sdk.pitpass.getTraderCodeInfo(code);
// info.code is the normalized wallet address

curl "https://staging.apimonaco.xyz/api/v1/pitpass/codes/0xabc..."

Returns 404 when the code does not resolve to a known wallet.

Pass the code on verify

Include referralCode in the auth verify request.

await sdk.auth.authenticate("688a21440e304c06b935f743dae88278", code);

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

For returning users the field is ignored. Self-referrals are silently dropped.

2. Get and display a user’s TraderCode

Fetch the authenticated user’s code to display it in the UI as a shareable link or copyable string.

await sdk.login("688a21440e304c06b935f743dae88278");

const { code, display, isCustom } = await sdk.pitpass.getMyTraderCode();
// `display` is ready to show ("Monaco - <address>", or the custom handle when set).
// `code` is the wallet-derived value to embed in a referral URL: ?ref=<code>
console.log(display, isCustom);

curl "https://staging.apimonaco.xyz/api/v1/pitpass/codes/me" \
  -H "X-Monaco-PublicKey: $MONACO_SESSION_PUBLIC_KEY" \
  -H "X-Monaco-Timestamp: $MONACO_TIMESTAMP" \
  -H "X-Monaco-Signature: $MONACO_SIGNATURE"

Response:

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

When the wallet has claimed a custom handle, customCode holds it (as entered), isCustom is true, and display is the handle.

3. Claim a custom handle (optional)

Let a user replace the wallet-derived default with a vanity handle. Preview availability as they type with the public check, then claim it. The handle is stored exactly as entered, must be letter-first [A-Za-z0-9_] and 5–20 characters, and is unique case-insensitively.

// Live availability feedback while the user types (public, no auth).
const { available, reason } = await sdk.pitpass.checkTraderCodeAvailability("acePilot");
if (!available) {
  // reason ∈ "taken" | "too_short" | "too_long" | "reserved" | "invalid_char" | "looks_like_address"
  console.log(`Unavailable: ${reason}`);
}

// Claim or edit (authenticated). The server is the authoritative gate.
const { display, isCustom } = await sdk.pitpass.setTraderCode("acePilot");
console.log(display, isCustom); // "acePilot", true

// Revert to the wallet-derived default.
await sdk.pitpass.clearTraderCode();

curl "https://staging.apimonaco.xyz/api/v1/pitpass/codes/available?code=acePilot"

curl -X PUT "https://staging.apimonaco.xyz/api/v1/pitpass/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" }'

setTraderCode maps rejections to 409 (handle already taken, or a recently-freed handle still in cooldown), 422 (validation, with a reason code), 429 (edited too frequently), and 403 (custom handles are disabled). clearTraderCode counts against the same rolling-hour edit limit, so it can also return 429 or 403. The public availability check is rate-limited and returns 429 once a caller exceeds the allowance — treat it as advisory feedback, not the authoritative gate.

4. Check rewards balance

Read accumulated rewards across all reward tokens. Returns an empty list if no rewards have been earned yet.

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

for (const entry of balances) {
  console.log(`${entry.token}: ${entry.available} raw units`);
}

curl "https://staging.apimonaco.xyz/api/v1/pitpass/rewards/balance" \
  -H "X-Monaco-PublicKey: $MONACO_SESSION_PUBLIC_KEY" \
  -H "X-Monaco-Timestamp: $MONACO_TIMESTAMP" \
  -H "X-Monaco-Signature: $MONACO_SIGNATURE"

Response:

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

available is in raw atomic units. Divide by the token’s decimals (e.g., 10^6 for USDC) to display a human-readable amount.

5. Transfer rewards to a trading balance

Move earned rewards from the rewards bucket into the authenticated application’s trading balance. The transfer is instant and ledger-only — no on-chain transaction.

const result = await sdk.pitpass.transferRewards({
  token: "0xusdc...",
  amount: "1200000", // raw atomic units, must be a positive integer string
});

console.log(result.rewardsBalance);  // remaining in rewards bucket after transfer
console.log(result.tradingBalance);  // new trading balance for this token

curl -X POST "https://staging.apimonaco.xyz/api/v1/pitpass/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 409 when the requested amount exceeds the available rewards balance.

Reward Rates

Reward rates are configured by Monaco and may change over time. Current testnet defaults:

Level	Relationship	Rate
L1	Direct referral’s trades	30% of net fee
L2	L1’s referral’s trades	15% of net fee
L3	L2’s referral’s trades	5% of net fee

Rewards are computed on the net fee (taker fee minus maker rebate) at fill time and credited instantly to the referrer’s rewards bucket. Missing levels — where the chain is shorter than 3 — are simply not paid.

Builder Checklist

Capture ?ref=CODE from the URL before the user completes sign-in, and pass it as sdk.auth.authenticate(clientId, code) or via the raw auth verify endpoint — sdk.login does not forward a referral code.
Validate the code with getTraderCodeInfo before showing a confirmation to the user; return a clean message on 404 instead of an error.
Never block sign-in on referral-code validation failures — a bad code is silently ignored server-side, but front-end validation errors should not prevent login.
Render the display field from getMyTraderCode rather than composing the display string yourself, and read isCustom to reflect whether a vanity handle is set.
In a custom-handle claim form, debounce checkTraderCodeAvailability for live feedback, but always handle 409/422/429 on setTraderCode — the server is the authoritative gate, not the advisory check.
Display available reward balances in human-readable form by dividing by the token’s decimal precision.
Handle 409 on transferRewards by refreshing the balance and showing the user their current available amount.

Earn for the product overview of TraderCodes and BuilderCodes
Auth for the full sign-in flow
TypeScript TraderCodes SDK for complete method signatures
REST — Get your TraderCode for the generated schema
REST — Look up a TraderCode for the generated schema
REST — Get rewards balance for the generated schema
REST — Transfer rewards for the generated schema

Learn

Build

Libraries

APIs

Resources

Surface Map

Concepts

Flow

2. Get and display a user’s TraderCode

3. Claim a custom handle (optional)

4. Check rewards balance

5. Transfer rewards to a trading balance

Reward Rates

Builder Checklist

​Surface Map

​Concepts

​Flow

​1. Capture a referral at signup

​2. Get and display a user’s TraderCode

​3. Claim a custom handle (optional)

​4. Check rewards balance

​5. Transfer rewards to a trading balance

​Reward Rates

​Builder Checklist

​Related References

Surface Map

Concepts

Flow

1. Capture a referral at signup

2. Get and display a user’s TraderCode

3. Claim a custom handle (optional)

4. Check rewards balance

5. Transfer rewards to a trading balance

Reward Rates

Builder Checklist

Related References