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

# CopyTradingService

> Copy trading: lead trader profiles, follows and the leaderboard

Package: `monaco.api.copy_trading`

Source: `protos/api/copy_trading.proto`

Use `CopyTradingService` to register as a lead trader, browse and follow lead traders, and manage your follows. A follow allocates collateral to a copy account (a cross risk bucket inside your margin account) and mirrors the leader's fills into it as market orders under your own account.

```protobuf theme={null}
service CopyTradingService {
  rpc UpsertLeadTrader(UpsertLeadTraderRequest) returns (UpsertLeadTraderResponse);
  rpc GetMyLeadTrader(GetMyLeadTraderRequest) returns (GetLeadTraderResponse);
  rpc ListMyFollowers(ListMyFollowersRequest) returns (ListMyFollowersResponse);
  rpc ListLeadTraders(ListLeadTradersRequest) returns (ListLeadTradersResponse);
  rpc GetLeadTrader(GetLeadTraderRequest) returns (GetLeadTraderResponse);
  rpc ListLeadTraderClosedTrades(ListLeadTraderClosedTradesRequest) returns (ListLeadTraderClosedTradesResponse);
  rpc ListLeadTraderOpenPositions(ListLeadTraderOpenPositionsRequest) returns (ListLeadTraderOpenPositionsResponse);
  rpc UpsertFollow(UpsertFollowRequest) returns (UpsertFollowResponse);
  rpc StopFollow(StopFollowRequest) returns (StopFollowResponse);
  rpc ListMyFollows(ListMyFollowsRequest) returns (ListMyFollowsResponse);
  rpc GetFollow(GetFollowRequest) returns (GetFollowResponse);
  rpc ListFollowLeaderPositions(ListFollowLeaderPositionsRequest) returns (ListFollowLeaderPositionsResponse);
  rpc PreviewFollow(PreviewFollowRequest) returns (PreviewFollowResponse);
}
```

## Notes

* `ListLeadTraders`, `GetLeadTrader` and `ListLeadTraderClosedTrades` are public (no auth). Every other RPC requires authentication and is scoped to the session's account.
* A leader is addressed by their custom TraderCode handle. The sequencer allows one lead profile per wallet (a second application's registration from the same wallet is refused with `INVALID_ARGUMENT`), so a handle names one leader; a leader without a custom handle is not publicly addressable and is not listed. Users appear by wallet address and a `display` string (the custom handle when claimed), never an internal id. `GetLeadTrader` returns `NOT_FOUND` for a suspended leader.
* `UpsertLeadTrader` registers you or edits your profile. A registration must meet the platform's eligibility rules (account equity, trading history, closed positions, and a claimed custom TraderCode handle); a refused registration returns `INVALID_ARGUMENT` naming the rule. The profile is replaced as sent: an omitted `bio` or `min_allocation` clears it, an omitted `status` means `ACTIVE`, and an omitted `share_bps` keeps your current share.
* `UpsertFollow` without `follow_id` creates a follow; with it, edits one of your follows. An edit takes the leader from the follow, so it keeps working after the leader releases their handle (`leader` may be empty; a handle naming a different leader is refused). `copy_existing` on a create also copies the leader's open positions into the new copy account; it applies only to a create (`INVALID_ARGUMENT` on an edit), and the follow keeps recording whether it copied at creation.
* `PreviewFollow` shows what a follow with those terms would open if it set `copy_existing`, as totals only: `estimated_margin` (what the copies would reserve at placement) and `estimated_fee`, both rounded up to cents, plus `copied_positions`, `skipped_positions` and `truncated`. It names no market, side or reason: the caller does not follow the leader yet. It is read-only and has the same session and terms rules as `UpsertFollow`: `PERMISSION_DENIED` for delegated agent and sub-account sessions, `NOT_FOUND` for an unknown or suspended leader, `INVALID_ARGUMENT` for terms a follow would refuse, and `FAILED_PRECONDITION` while copy trading is off. It spends the order-risk preview budget and the engine's preview lane share. At most 64 positions are sized; `truncated` is set when more matched.
* `StopFollow` stops one of your own follows. It is an exit and is never gated: only ownership applies (a banned or sub-account session can still stop its own follow), except that a delegated agent session cannot. It stays available during an operations block; registrations and follows do not.
* `ListLeadTraderOpenPositions` is visible only to the leader's current followers (a live follow in the session's application); anyone else gets `PERMISSION_DENIED`. It is addressed by handle, so once a leader releases their handle it answers `NOT_FOUND` even for current followers, who still see the follow through `ListMyFollows` and `GetFollow`, and the leader's positions through `ListFollowLeaderPositions`.
* `ListFollowLeaderPositions` lists the open positions of the leader one of your follows copies, taking the leader from the follow. `NOT_FOUND` unless the follow is yours; `PERMISSION_DENIED` unless it is live (`ACTIVE` or `CLOSE_ONLY`).
* `GetFollowResponse.copy_account_equity` is the copy account's equity at the engine's marks: its collateral plus the unrealized PnL of its positions. It is a balance, not trading PnL, and it is absent when the engine cannot be read.
* Delegated agent sessions and sub-account sessions cannot register or follow (`PERMISSION_DENIED`); a delegated agent session cannot stop a follow either. A follow or profile that is not yours returns `NOT_FOUND`.
* When copy trading is switched off, registrations and new follows return `FAILED_PRECONDITION`.
* Stats (`LeadTraderStats`) come from the leader's account PnL rollups over 7d, 30d, 90d and all-time. `pnl` is trading PnL (realized plus unrealized, net of fees and funding). `roi_pct` divides it by the highest base balance over the window (starting equity plus net deposits), so a withdrawal cannot inflate it; it is absent when that base is not positive. `max_drawdown_pct` is the largest peak-to-trough fall of cumulative PnL over the same base, sampled at the window's rollup interval (1h for 7d, 4h for 30d and 90d, 1d for all-time). `win_rate_pct` counts winning over winning plus losing closes. A risk bucket's cash balance never feeds these figures.
* `LeadTraderFollowSummary.allocated` is the collateral allocated by live follows (AUM as allocated, not marked to market). `aum_equity` is the same AUM marked: the summed equity of the live follows' copy accounts at the engine's marks, absent when it could not be read. `sort=aum` ranks by it, with leaders lacking it last.
* `ListLeadTraders` serves a leaderboard snapshot refreshed about once a minute (`as_of`); it lists `ACTIVE` leaders only, sorted highest first by `sort`, with leaders lacking a value for the metric last.
* Lists use cursor pagination: omit `page_token` for the first page, then send each response's `next_page_token` until it is empty. A token only works with the filters and sort that produced it (`INVALID_ARGUMENT` otherwise). There are no totals. Page size: up to 1000 on your own lists (`ListMyFollows`, `ListMyFollowers`), up to 100 on the public lists.