Skip to main content
The PitPass hooks wrap the sdk.pitpass.* methods of @0xmonaco/core. Each is a thin useCallback wrapper that resolves the client from the MonacoProvider context, so the request, validation, and casing behaviour are owned by the core client. Import each hook directly from @0xmonaco/react.

​
useMyTraderCode

​
() => Promise<TraderCodeResponse>
Read the authenticated caller’s TraderCode identity. Requires authentication.Returns:
  • code: string - The permanent wallet-derived TraderCode (normalized wallet address)
  • createdAt: string - RFC 3339 timestamp when the code row was first derived
  • customCode: string - The custom vanity handle exactly as entered, or "" when the wallet-derived default is kept
  • isCustom: boolean - True when a custom handle is set
  • display: string - The single human-facing string to render (custom handle when set, otherwise the Monaco - <address> default form)

​
useSetTraderCode

​
(code: string) => Promise<TraderCodeResponse>
Claim or edit the caller’s custom (vanity) TraderCode handle. Requires authentication.Parameters:
  • code: string - The custom handle. Validated client-side (letter-first [A-Za-z0-9_], length 5–20) and sent exactly as entered; casing is preserved
Returns: the same TraderCodeResponse shape as useMyTraderCode, reflecting the new custom handle.

​
useClearTraderCode

​
() => Promise<TraderCodeResponse>
Clear the caller’s custom TraderCode handle, reverting to the wallet-derived default. The freed handle enters a cooldown before it can be reclaimed. Requires authentication.Returns: the TraderCodeResponse shape, now with the wallet-derived default in effect.

​
useTraderCodeAvailability

​
(code: string) => Promise<TraderCodeAvailabilityResponse>
Public, unauthenticated advisory check of whether a custom handle is available (as-you-type UX). Advisory only — the authoritative gate is the atomic claim in useSetTraderCode, so a positive result is not a reservation.Parameters:
  • code: string - The candidate custom handle
Returns:
  • available: boolean - True when the handle passes validation and is neither live nor cooling down
  • reason: “taken” | “too_short” | “too_long” | “reserved” | “invalid_char” | “looks_like_address” (optional) - Present only when unavailable

​
useTraderCodeInfo

​
(code: string) => Promise<TraderCodeInfoResponse>
Public lookup of a TraderCode by wallet address, used at sign-up to validate a referral code before applying it. No authentication required.Parameters:
  • code: string - The bare wallet address or the Monaco - <address> display form
Returns:
  • code: string - The resolved TraderCode (normalized wallet address)

​
useRewardsBalance

​
() => Promise<GetRewardsBalanceResponse>
Read the authenticated caller’s current PitPass rewards-bucket balances. Requires authentication.Returns:
  • balances: { token: string; available: string }[] - One entry per reward token with a non-zero available balance. available is in RAW atomic units of the token

​
useTransferRewards

​
(params: TransferRewardsParams) => Promise<TransferRewardsResponse>
Transfer earned PitPass rewards into a tradeable balance. Parameters are validated by the SDK core using Zod. Requires authentication.Parameters:
  • token: string - Reward token contract address (0x-prefixed) to transfer
  • amount: string - Amount to transfer, in RAW atomic units of the token (positive integer string)
Returns:
  • rewardsBalance: string - Your rewards-bucket balance after the transfer, RAW atomic units
  • tradingBalance: string - Your trading balance for the token after the transfer, RAW atomic units

​
useMyReferralPosition

​
() => Promise<GetMyReferralPositionResponse>
Read the authenticated caller’s own referral position. Self-scoped — only ever returns your own chain. Requires authentication.Returns:
  • referrer: string - Wallet address of your direct (L1) referrer, or "" when you were not referred
  • upline: { wallet, display, level }[] - Your referral chain upward, nearest first (L1, L2, and so on), at most as many entries as PitPass rewards levels (never more than 10); empty when you were not referred
  • referrerDisplay: string - The referrer’s custom handle if claimed, otherwise the wallet address
  • totalEarned: string - All-time rewards you have earned, RAW atomic units
  • rewards: { source, sourceDisplay, level, amount, token, rateApplied, createdAt }[] - Up to your 100 most recent reward rows (totalEarned remains the complete aggregate); level is 1 for a direct referee’s fills, 2 for their referee’s, and so on (at most 10)

​
useMyReferralDownline

​
(params?: { pageSize?: number; pageToken?: string }) => Promise<GetMyReferralDownlineResponse>
Read who you earn from and how much. Self-scoped, read-only. Requires authentication.earningsBySource is paged. Called without params, it returns only the first page (up to 100 rows), not every row — follow nextPageToken until it is "" to read the rest.Parameters:
  • pageSize?: number - earningsBySource rows per page, 1-500 (default 100)
  • pageToken?: string - Opaque nextPageToken from the previous response; omit for the first page
Returns:
  • earningsBySource: { source, sourceDisplay, level, totalEarned, token }[] - One page of rows, one per (source, level, token) across every reward level, ordered by each source account’s total, largest first, so the same trader can appear more than once (different level or token); source is not unique. 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 it can appear again on a later page
  • directReferees: { wallet, display, referredAt, totalEarned }[] - Your direct (L1) referees, including non-traders ("0" earned); up to the 500 most recent effective referees from a bounded scan, so a very large history may be incomplete (the earnings views stay complete)
  • summary: { totalEarned, byLevel, level1Earned, level2Earned, level3Earned } - Earnings broken down by level, covering every level and source regardless of the page. byLevel is { level, earned }[] (raw atomic units), ascending, one entry per level with earnings, including levels deeper than PitPass rewards today. level1Earned, level2Earned, and level3Earned are deprecated (levels 1-3 only) - use byLevel
  • nextPageToken: string - Pass it back as pageToken for the next page; "" when there are no more rows
Errors: a ValidationError before sending when pageSize is outside 1-500; 400 for a malformed pageToken; 401 when unauthenticated; 429 when the account’s read budget is exhausted (retry after the interval in the error detail); 500 on a server error

​
useMyReferralTree

​
(params?: GetMyReferralTreeParams) => Promise<GetMyReferralTreeResponse>
Read one level of your referral tree: your L1 referees when parent is omitted, or the referees of one of your own referees above the deepest rewarded level when it is set. Self-scoped, read-only. Requires authentication.Parameters:
  • parent?: string - Wallet whose direct referees to list; any wallet that is not you or one of your referees above the deepest rewarded level returns 404
  • pageSize?: number - Nodes per page, 1-200 (default 50)
  • pageToken?: string - nextPageToken from the previous page (same parent)
Returns:
  • parent: string - The wallet whose referees are listed
  • parentLevel: number - 0 for you, 1-9 for an expanded referee
  • nodes: { wallet, display, level, parent, referredAt, refereeCount, totalEarned }[] - Newest first; level is the depth below you (1-10); expand a node when refereeCount > 0 (always 0 at the deepest rewarded level); totalEarned is what you earned from that wallet’s own trades
  • nextPageToken: string - Cursor for the next page, "" on the last page