> ## 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.

# TraderCodes hooks

> React hooks for TraderCodes referral codes and rewards

The TraderCodes hooks wrap the `sdk.tradercodes.*` 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

```tsx theme={null}
import { useMyTraderCode } from "@0xmonaco/react";

const { getMyTraderCode } = useMyTraderCode();
```

<ResponseField name="getMyTraderCode" type="() => 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)
</ResponseField>

## useSetTraderCode

```tsx theme={null}
import { useSetTraderCode } from "@0xmonaco/react";

const { setTraderCode } = useSetTraderCode();
```

<ResponseField name="setTraderCode" type="(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.
</ResponseField>

## useClearTraderCode

```tsx theme={null}
import { useClearTraderCode } from "@0xmonaco/react";

const { clearTraderCode } = useClearTraderCode();
```

<ResponseField name="clearTraderCode" type="() => 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.
</ResponseField>

## useTraderCodeAvailability

```tsx theme={null}
import { useTraderCodeAvailability } from "@0xmonaco/react";

const { checkTraderCodeAvailability } = useTraderCodeAvailability();
```

<ResponseField name="checkTraderCodeAvailability" type="(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
</ResponseField>

## useTraderCodeInfo

```tsx theme={null}
import { useTraderCodeInfo } from "@0xmonaco/react";

const { getTraderCodeInfo } = useTraderCodeInfo();
```

<ResponseField name="getTraderCodeInfo" type="(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)
</ResponseField>

## useRewardsBalance

```tsx theme={null}
import { useRewardsBalance } from "@0xmonaco/react";

const { getRewardsBalance } = useRewardsBalance();
```

<ResponseField name="getRewardsBalance" type="() => Promise<GetRewardsBalanceResponse>">
  Read the authenticated caller's current TraderCodes 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
</ResponseField>

## useTransferRewards

```tsx theme={null}
import { useTransferRewards } from "@0xmonaco/react";

const { transferRewards } = useTransferRewards();
```

<ResponseField name="transferRewards" type="(params: TransferRewardsParams) => Promise<TransferRewardsResponse>">
  Transfer earned TraderCodes 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
</ResponseField>

## useMyReferralPosition

```tsx theme={null}
import { useMyReferralPosition } from "@0xmonaco/react";

const { getMyReferralPosition } = useMyReferralPosition();
```

<ResponseField name="getMyReferralPosition" type="() => 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 TraderCodes 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)
</ResponseField>

## useMyReferralDownline

```tsx theme={null}
import { useMyReferralDownline } from "@0xmonaco/react";

const { getMyReferralDownline } = useMyReferralDownline();
```

<ResponseField name="getMyReferralDownline" type="(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 TraderCodes 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
</ResponseField>

## useMyReferralTree

```tsx theme={null}
import { useMyReferralTree } from "@0xmonaco/react";

const { getMyReferralTree } = useMyReferralTree();
```

<ResponseField name="getMyReferralTree" type="(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
</ResponseField>


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