CopyTradingService

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.