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

# Copy Trading

> Lead traders publish a track record; followers mirror their perp fills into a dedicated copy account.

Copy trading lets a follower mirror a lead trader's perpetual futures fills into their own margin account. The follower allocates collateral to a per-leader **copy account**, and every fill the leader makes is mirrored into it in the same sequencer step, as market orders placed under the follower's own account. Leaders earn a share of their followers' realized profit.

## Surface Map

| Surface | Use |
| - | - |
| REST | Public: `GET /api/v1/copy-trading/leaders`, `GET /api/v1/copy-trading/leaders/{leader}`, `GET /api/v1/copy-trading/leaders/{leader}/closed-trades`. Authenticated: `PUT` and `GET /api/v1/copy-trading/leaders/me`, `GET /api/v1/copy-trading/leaders/me/followers`, `GET /api/v1/copy-trading/leaders/{leader}/positions`, `POST` and `GET /api/v1/copy-trading/follows`, `GET /api/v1/copy-trading/follows/{followId}`, `GET /api/v1/copy-trading/follows/{followId}/leader-positions`, `POST /api/v1/copy-trading/follows/preview`, `POST /api/v1/copy-trading/follows/{followId}/stop` |
| TypeScript SDK | `sdk.copyTrading.*` — see [Copy trading (SDK)](/sdk/typescript/copy-trading) |
| React SDK | `useCopyTrading()`, `useCopyEvents()` — see [useCopyTrading](/sdk/react/hooks/use-copy-trading) |
| WebSocket | The owner-private [`copy` channel](/reference/websockets#copy): follow state changes and skipped mirrors, for the follower |
| gRPC | [`CopyTradingService`](/grpc/protos/copy-trading) |
| MCP | `list_lead_traders`, `get_lead_trader`, `upsert_follow`, `stop_follow` and the other copy trading tools — see [MCP server](/sdk/mcp-server) |

## Concepts

**Lead trader.** A wallet that has registered a lead profile. Leaders are addressed everywhere by their **custom TraderCode handle** (see [TraderCodes](/developers/tradercodes)), and one wallet holds at most one lead profile, so a handle names exactly one leader. Every other user appears by public wallet address plus a display name, never by an internal id. A leader's profile carries a status: `ACTIVE` accepts new follows, `PAUSED` keeps existing follows mirroring but accepts no new ones, and `SUSPENDED` (set by the platform) hides the leader from public reads.

**Follow and copy account.** A follow is one follower's relationship with one leader. Creating it moves the allocation from the follower's margin account into a new **copy account**: a cross risk bucket in the follower's margin account that holds only this follow's collateral and positions. The follow's `copyRiskBucketId` names it, and the account listings label its rows with `copyFollowId` and `copyLeaderHandle`. Isolated copies open isolated risk buckets tied to the same follow.

**Sizing, leverage and margin mode.** Each follow chooses:

* `sizingMode`: `PROPORTIONAL` (default) scales each copy by the copy account's equity over the leader's margin account equity; `FIXED_MARGIN` commits `sizingParam` quote units of margin per leader order.
* `leverageMode`: `FOLLOW` (default) uses the leader's leverage; `FIXED` uses `fixedLeverage` for every copy.
* `marginModePolicy`: `FOLLOW` (default) copies into the leader's margin mode per market; `CROSS` or `ISOLATED` forces one.
* `tradingPairIds`: the markets to copy; empty copies every market the leader trades.

**Skips and close-only.** A leader fill that cannot be mirrored is **skipped** with a reason: `INSUFFICIENT_MARGIN`, `BELOW_MIN`, `LEVERAGE_MISMATCH`, `MARKET_STATE`, `LEADER_EQUITY` or `NO_LIQUIDITY`. Only `INSUFFICIENT_MARGIN` counts toward the follow's `consecutiveSkips` streak. A follow in `CLOSE_ONLY` mirrors reductions only.

**Stop-loss and stopping.** `slPct` sets a copy stop-loss as a fraction of the allocation, in `(0, 1]`. A follow stops when the follower stops it, the stop-loss triggers, the skip limit is reached, the leader is suspended, or an admin stops it; `stopReason` says which.

**Profit share basis.** Each follow tracks `cumNetRealized` (realized PnL net of fees since the follow started) and its high-water mark `hwm`. These are the basis for the leader's profit share. They are **not** the copy account's balance: on a risk bucket row, `realizedPnl` is the risk bucket's cash balance, which also moves on transfers with no trade.

**Copy orders.** Orders placed for a follow carry `origin: "COPY"` and the follow's id as `copyRelationshipId` on their [order events](/sdk/typescript/websockets#order-event-types).

## Flow for followers

### 1. Find a leader

The leaderboard, a leader's profile and their closed trades are public — no session needed.

```typescript theme={null}
const { leaders, nextPageToken } = await sdk.copyTrading.listLeadTraders({ sort: "roi", window: "30d" });
for (const { profile, followSummary, stats } of leaders) {
  console.log(profile.leader.display, stats.roiPct, stats.maxDrawdownPct, followSummary.followerCount);
}

const leader = await sdk.copyTrading.getLeadTrader("alpha_trader");
const { closedTrades } = await sdk.copyTrading.listLeadTraderClosedTrades("alpha_trader", { pageSize: 50 });
```

Lists are cursor paged: pass the previous response's `nextPageToken` (with the same `sort` and `window` for the leaderboard) until it comes back empty. There are no totals.

### 2. Follow

```typescript theme={null}
const { followId, copyRiskBucketId } = await sdk.copyTrading.upsertFollow({
  leader: "alpha_trader",
  allocation: "1000",
  sizingMode: "PROPORTIONAL",
  slPct: "0.25",
});
```

The allocation must be at or above the platform minimum and the leader's `minAllocation`. Delegated agent and sub-account sessions cannot follow. To also copy the leader's already-open positions into the new copy account, set `copyExisting: true` on the create. Each copy is sized like a mirrored fill. `previewFollow` shows what that would open before you commit, as totals only: the estimated margin the copies would reserve and their fees (rounded up to cents), and how many of the leader's positions would and would not be copied. It names no market, side or reason, since you do not follow the leader yet. It is read-only, applies the same terms rules as a follow (so it refuses terms a follow would refuse), is refused while copy trading is off, and spends the [order-risk preview budget](/developers/rate-limits#reads). It sizes at most 64 positions and sets `truncated` when the leader holds more in the copied markets. `copyExisting` applies only to a create: an edit that sets it is refused, and the follow keeps recording whether it copied at creation.

```typescript theme={null}
const { estimatedMargin, estimatedFee, copiedPositions, skippedPositions } = await sdk.copyTrading.previewFollow({ leader: "alpha_trader", allocation: "1000" });
await sdk.copyTrading.upsertFollow({ leader: "alpha_trader", allocation: "1000", copyExisting: true });
```

### 3. Watch the follow

```typescript theme={null}
const unsubscribe = sdk.ws.copy(
  (event) => {
    if (event.eventType === "copy_skip") {
      console.warn(`skipped ${event.data.requestedQuantity} on ${event.data.tradingPairId}: ${event.data.reason}`);
    } else {
      console.log(`follow ${event.data.relationshipId} is ${event.data.status} (${event.data.change})`);
    }
  },
  (follows) => console.log(`${follows.length} live follows`),
);
```

Current followers can also read the leader's open positions with `listLeadTraderOpenPositions(handle)`, or by follow with `listFollowLeaderPositions(followId)`, which takes the leader from the follow and so keeps working after the leader releases their handle. `getFollow(followId)` returns a follow with its most recent skips and `copyAccountEquity`: the copy account's equity at the engine's marks (its collateral plus the unrealized PnL of its positions). That is a balance, not trading PnL, and it is absent when the engine cannot be read.

### Copy positions are the follow's

The positions in a copy account are managed by the follow:

* TP/SL cannot be attached to a copy position (403).
* A manual close, single or close-all, still works, but it goes out immediate-or-cancel, so no order is left resting in the copy account.
* No order, transfer or simulate accepts a strategy key starting with `copy:` (400 `strategy keys starting with copy: are reserved`). Collateral moves into or out of a copy account only through the follow: its allocation, an edit, or a stop.

### 4. Edit or stop

An edit sends `followId` and **replaces** the follow's settings: every optional setting you leave out reverts to its default, so an edit without `slPct` removes the stop-loss. The leader comes from the stored follow, so `leader` can be omitted.

```typescript theme={null}
await sdk.copyTrading.upsertFollow({ followId, allocation: "1500", slPct: "0.2" });
await sdk.copyTrading.stopFollow(followId);
```

Stopping is never gated beyond ownership, except that a delegated agent session cannot stop a follow.

## Flow for leaders

### 1. Register

A registration is checked against the platform's eligibility rules — account equity, trading history, closed positions, and a claimed custom TraderCode handle. A refusal names the rule. A wallet with a live follow cannot register.

```typescript theme={null}
const { created, status, shareBps } = await sdk.copyTrading.upsertLeadTrader({ shareBps: 1000, bio: "BTC momentum" });
```

The profile is replaced as sent: an omitted `bio` or `minAllocation` is cleared and an omitted `status` means `ACTIVE`; an omitted `shareBps` keeps the current share (the platform default on a registration).

### 2. Pause and review followers

```typescript theme={null}
await sdk.copyTrading.upsertLeadTrader({ shareBps: 1000, bio: "BTC momentum", status: "PAUSED" });
const { followers } = await sdk.copyTrading.listMyFollowers({ pageSize: 100 });
const me = await sdk.copyTrading.getMyLeadTrader();
```

## Errors

| Status | When |
| - | - |
| 400 | Invalid request, or refused by a rule (eligibility, allocation minimum, a paused leader); the message names the rule |
| 401 | An authenticated call without a session |
| 403 | A delegated agent or sub-account session registering or following; a non-follower reading a leader's open positions; a stopped follow's leader positions; TP/SL on a copy position |
| 404 | An unknown or suspended leader; a follow that is not yours |
| 409 | Copy trading is not available |
| 503 | The matching engine is unavailable; retry |