TraderCodes (PitPass)

import { MonacoSDK } from "@0xmonaco/core";

// Get the authenticated user's TraderCode (with custom-handle fields)
await sdk.pitpass.getMyTraderCode();

// Claim or edit a custom (vanity) handle
await sdk.pitpass.setTraderCode(code);

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

// Advisory check of a handle's availability (public, no auth required)
await sdk.pitpass.checkTraderCodeAvailability(code);

// Validate a referral code (public, no auth required)
await sdk.pitpass.getTraderCodeInfo(code);

// Read accrued rewards
await sdk.pitpass.getRewardsBalance();

// Move rewards into a trading balance
await sdk.pitpass.transferRewards({ token, amount });

For a full integration walkthrough see TraderCodes.

() => Promise<TraderCodeResponse>

Return the authenticated caller’s TraderCode. The default code is derived from the wallet address and is created on demand — this method never returns NOT_FOUND for a signed-in user.Requires authentication.Returns: TraderCodeResponse:

code: string — the wallet-derived code (normalized lowercase hex address)
createdAt: string — ISO 8601 timestamp of when the code row was first derived
customCode: string — the claimed custom handle as entered, or an empty string when the wallet-derived default is kept
isCustom: boolean — whether a custom handle is currently set
display: string — the string to show users (Monaco - <address> for the default, or the custom handle)

Example:

const { code, display, isCustom } = await sdk.pitpass.getMyTraderCode();
// Render `display` directly; embed `code` in a referral URL: ?ref=<code>
console.log(display, isCustom);

(code: string) => Promise<TraderCodeResponse>

Claim or edit the caller’s custom (vanity) handle. The handle is stored exactly as entered (casing preserved) but is unique case-insensitively; it must be letter-first, [A-Za-z0-9_], and 5–20 characters. The SDK validates the handle client-side before sending, but the server remains the authoritative gate.Requires authentication.Parameters:

code: string — the desired handle

Returns: TraderCodeResponse — the updated code, with isCustom: true and customCode set.Throws 409 when the handle is already taken (case-insensitive) or is a recently-freed handle still in cooldown, 422 on validation failure (the error carries a stable reason code), 429 when handles are edited too frequently, and 403 when custom handles are disabled.Example:

const { display, isCustom } = await sdk.pitpass.setTraderCode("acePilot");
console.log(display, isCustom); // "acePilot", true

() => Promise<TraderCodeResponse>

Drop the caller’s custom handle and revert to the wallet-derived default. Idempotent — clearing when no handle is set simply returns the default code.Requires authentication.Returns: TraderCodeResponse — the code with isCustom: false and an empty customCode.Clearing counts against the same rolling-hour edit limit as setTraderCode, so it throws 429 when edited too frequently and 403 when custom handles are disabled.Example:

const { display, isCustom } = await sdk.pitpass.clearTraderCode();
console.log(isCustom); // false

(code: string) => Promise<TraderCodeAvailabilityResponse>

Public advisory check of whether a custom handle can be claimed. Use it for live feedback in a claim form; it is not the authoritative gate — setTraderCode still validates on the server.No authentication required. Rate-limited per client (throws 429 once the caller exceeds the allowance).Parameters:

code: string — the handle to check

Returns: TraderCodeAvailabilityResponse:

available: boolean — whether the handle can be claimed
reason?: string — present only when unavailable; one of taken, too_short, too_long, reserved, invalid_char, or looks_like_address

Example:

const { available, reason } = await sdk.pitpass.checkTraderCodeAvailability("acePilot");
if (!available) {
  console.log(`Unavailable: ${reason}`);
}

(code: string) => Promise<TraderCodeInfoResponse>

Public lookup for a TraderCode. Accepts a bare wallet address or the Monaco - <address> display form. Use this to validate a referral code before showing a confirmation to the user.No authentication required.Parameters:

code: string — wallet address or Monaco - <address> display form

Returns: TraderCodeInfoResponse:

code: string — normalized wallet address

Throws 404 when the code does not resolve to a known wallet.Example:

try {
  const info = await sdk.pitpass.getTraderCodeInfo("0xabc...");
  console.log(info.code); // normalized address
} catch (err) {
  // 404 — code is not recognized; show a friendly message
}

() => Promise<GetRewardsBalanceResponse>

Return the caller’s current rewards-bucket balances across all reward tokens. Rewards accrue here as referred users trade. Returns an empty balances array if no rewards have been earned.Requires authentication.Returns: GetRewardsBalanceResponse:

balances: RewardsBalanceEntry[]:
- token: string — reward token contract address (0x-prefixed)
- available: string — raw atomic units (divide by token decimals for display)

Example:

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

for (const entry of balances) {
  const display = Number(entry.available) / 1e6; // USDC has 6 decimals
  console.log(`${display} USDC available`);
}

(params: TransferRewardsParams) => Promise<TransferRewardsResponse>

Move earned rewards from the rewards bucket into the authenticated application’s trading balance. The transfer is ledger-only — no on-chain transaction, no gas. Funds are available for trading immediately after the transfer.Requires authentication.Parameters: TransferRewardsParams:

token: string — token contract address (0x-prefixed EVM address)
amount: string — positive integer string in raw atomic units (e.g. "1000000" for 1 USDC)

Returns: TransferRewardsResponse:

rewardsBalance: string — remaining balance in the rewards bucket after the transfer (raw atomic units)
tradingBalance: string — new trading balance for this token after the transfer (raw atomic units)

Throws 409 when the requested amount exceeds the available rewards balance.Example:

const { rewardsBalance, tradingBalance } = await sdk.pitpass.transferRewards({
  token: "0xusdc...",
  amount: "1000000", // 1 USDC in raw units
});

console.log(`Remaining rewards: ${rewardsBalance}`);
console.log(`New trading balance: ${tradingBalance}`);

() => Promise<GetMyReferralPositionResponse>

Read the authenticated caller’s own referral position. Self-scoped — the server derives your identity from the session, so it only ever returns your own chain. Requires authentication.Returns: GetMyReferralPositionResponse:

referrer: string — the wallet address of your direct (L1) referrer, or "" when you were not referred. Use the empty check to drive an “already referred” state.
referrerDisplay: string — the referrer’s custom TraderCode handle if they have claimed one, otherwise their wallet address (render this).
totalEarned: string — all-time rewards you have earned, in raw atomic units.
rewards: array of up to your 100 most recent reward rows (totalEarned remains the complete aggregate), each { source, sourceDisplay, level, amount, token, rateApplied, createdAt } — source/sourceDisplay identify the trader whose fills paid you.

Throws 401 when unauthenticated, 429 when the account’s read budget is exhausted (retry after the interval in the error detail), and 500 on a server error.Example:

const { referrer, referrerDisplay, totalEarned } = await sdk.pitpass.getMyReferralPosition();
if (referrer) console.log(`Referred by ${referrerDisplay}`);

() => Promise<GetMyReferralDownlineResponse>

Read who you earn from and how much. Self-scoped, read-only. Requires authentication.Returns: GetMyReferralDownlineResponse:

earningsBySource: array of { source, sourceDisplay, level, totalEarned, token } — one row per (source, level, token) across all three reward levels (L1/L2/L3), so the same trader can appear more than once (a different level or token); source is not unique.
directReferees: array of { wallet, display, referredAt, totalEarned } — your direct (L1) referees, including those who have not traded yet (totalEarned: "0"). Shows up to the 500 most recent effective referees (after wallet dedupe), drawn from a bounded scan, so a very large history may yield an incomplete roster; the earnings views stay unbounded.
summary: { totalEarned, level1Earned, level2Earned, level3Earned } — your earnings broken down by level.

Throws 401 when unauthenticated, 429 when the account’s read budget is exhausted (retry after the interval in the error detail), and 500 on a server error.Example:

const { earningsBySource, summary } = await sdk.pitpass.getMyReferralDownline();
console.log(`Total earned: ${summary?.totalEarned}, from ${earningsBySource.length} sources`);

Learn

Build

Libraries

APIs

Resources