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

> TraderCode management.

## TraderCodes

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();
```

**getMyTraderCode** `() =\> 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

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

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

**setTraderCode** `(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

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

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

**clearTraderCode** `() =\> 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

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

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

**checkTraderCodeAvailability** `(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

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

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

**getTraderCodeInfo** `(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

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

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

**getRewardsBalance** `() =\> 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

### useTransferRewards

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

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

**transferRewards** `(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

### useMyReferralPosition

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

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

**getMyReferralPosition** `() =\> 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)

### useMyReferralDownline

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

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

**getMyReferralDownline** `(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

### useMyReferralTree

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

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

**getMyReferralTree** `(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


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