Copy Trading¶
Client REST API for the desktop/web trading terminal copy trading flow.
This API uses the new copy trading model:
CopyMasteris a strategy profile attached to a normal trading account.CopyFollowerstores account-level copying settings for a normal trading account. The terminal creates this profile automatically during subscription and does not expose a separate profile/settings section.CopySubscriptionlinks a follower account to a master account.- Trading accounts remain normal
AccountRecordrecords. The legacyMASTER/SLAVEaccount model is deprecated. - The master marketplace endpoint returns calculated statistics for discovery and ranking for the requested period: ROI, PNL, win rate, max drawdown, average PNL per trade and trade counts.
- Masters can explicitly allow public trade-history viewing with
show_trade_historyand public follower statistics withshow_followers. When disabled, these public endpoints do not expose the corresponding data. - A master can be created only from a REAL account. DEMO accounts can be followers only when the master policy allows demo followers.
- Master creation requires choosing a reward policy in the same request.
Terminal subscription flow¶
To start copying, the customer selects a trading account, opens the master marketplace, chooses a master and submits a subscription. The server creates a default follower profile together with the first subscription when that account does not have one yet. Customers do not need to create a follower profile as a separate step.
Account-level options such as whether copying is enabled, manual-trading policy and the maximum number of active masters remain configurable through the administrative interface and existing profile APIs. These settings describe the account and apply to its subscriptions; they are not a prerequisite that must be configured before selecting a master. The profile remains after its final subscription is removed so the customer can retain those settings.
Most customer management endpoints require SESSION_CUSTOMER. The public master
trade-history endpoint accepts any authenticated terminal/CRM/manager session,
but returns data only when the master enabled the corresponding public flag
(show_trade_history or show_followers). The server validates account
ownership from the session and never trusts customer_id from the request body.
Endpoints¶
| Method | Path | Description |
| GET | /copytrade/masters | GetCopyTradeMasters |
| GET | /copytrade/master/stats | GetCopyTradeMasterStats |
| GET | /copytrade/master/trades | GetCopyTradeMasterTradesByFilter |
| GET | /copytrade/master/followers | GetCopyTradeMasterFollowersByFilter |
| GET | /copytrade/my | GetCopyTradeMy |
| GET | /copytrade/subscriptions | GetCustomerSubscriptionsByFilter |
| POST | /copytrade/master | CreateCopyTradeMaster |
| PUT | /copytrade/master/{id} | UpdateCopyTradeMaster |
| DELETE | /copytrade/master/{id} | DeleteCopyTradeMaster |
| POST | /copytrade/follower | CreateCopyTradeFollower (optional explicit profile management; not required before subscribing) |
| PUT | /copytrade/follower/{id} | UpdateCopyTradeFollower |
| DELETE | /copytrade/follower/{id} | DeleteCopyTradeFollower |
| POST | /copytrade/subscription | CreateCopyTradeSubscription |
| PUT | /copytrade/subscription/{id} | UpdateCopyTradeSubscription |
| DELETE | /copytrade/subscription/{id} | DeleteCopyTradeSubscription |
| GET | /copytrade/trade-links | GetCopyTradeLinks |
| GET | /copytrade/rewards | GetCopyTradeRewards |
Runtime execution and access behavior¶
Copy processing is event-driven through trade.push. It uses the CopyTradeManager
cache and routes follower operations through the normal trading API. A copy is
eligible only while the subscription is enabled and active and both the master
and follower profiles are enabled. The same gate applies to opening, closing,
and reconciliation. Linked follower orders are excluded from re-copying.
copy_mode controls ongoing synchronization: FULL_SYNC opens, updates and
closes linked orders; OPEN_ONLY opens but does not update or close linked
orders; CLOSE_ONLY closes linked orders but does not open new copies. In
FULL_SYNC, copy_sl and copy_tp control level synchronization; reversing
direction swaps the SL/TP meaning. Partial-close synchronization follows
copy_partial_close.
When copy_pending_orders = 1, pending orders are copied with their master
price and expiration. FULL_SYNC also follows pending-order price, expiration
and enabled SL/TP changes; pending volume amendments are not synchronized. In close modes, cancelling a master pending order
cancels its linked follower pending order. Activation is master-driven: a
linked follower pending order activates only after its master pending order
activates. The existing follower ticket and link are preserved, including when
the reverse-mapped command has a different Bid/Ask trigger and that threshold
was crossed earlier at nonzero spread. Follower activation still uses normal
quote, margin and routing validation and requires the subscription, master and
follower to remain enabled and active. No second follower order is created.
With
reverse_direction = 1, pending commands map BUY_LIMIT ↔ SELL_STOP and
BUY_STOP ↔ SELL_LIMIT while preserving the requested price. If
copy_existing_positions = 1, initial replay includes pending orders only when
copy_pending_orders = 1.
Follower manual-write policy applies to authenticated user/customer requests on
trade opens, modifications, closes, pending-order changes and group operations.
Mode 0 rejects all such writes; mode 1 allows writes to non-copied orders
but rejects changes to copied orders; mode 2 allows both. Ownership is checked first. Staff and internal requests bypass this follower
policy. Manager trade-write commands using a user/customer context are subject
to the same checks. The errors are HTTP 403 COPY_MANUAL_TRADING_DISABLED
or COPY_COPIED_ORDER_MANUAL_FORBIDDEN, each with a message field. Group REST
close/cancel operations reject a matching protected order before changing any
order.
The active master limit counts distinct master logins for enabled active
subscriptions. The public create/update fields accept integers of at least 1 (default 1).
The limit counts distinct master logins; create/update/resume and lowering the
follower limit enforce the bound. An excess returns
RET_TRADE_LIMIT_REACHED (HTTP 409).
Ownership Rules¶
- Master create/update/delete is allowed only when
master.loginbelongs to the authenticated customer. - Master
loginmust belong to a REAL account group. - Follower create/update/delete is allowed only when
follower.loginbelongs to the authenticated customer. - Subscription create/update/delete is allowed only when
follower_loginbelongs to the authenticated customer. - When an update changes
master_loginorfollower_login, the resulting master/follower pair must not refer to the same account (RET_ERR_PARAMS, HTTP400) or duplicate another subscription (RET_ERR_DUPLICATE, HTTP409). The current subscription is excluded from duplicate detection. Existing records with unchanged logins remain editable. POST /copytrade/subscriptioncan create the follower profile automatically when it is absent. The default profile is enabled, permits manual trading on non-copied orders, and allows one active master. Existing enabled profiles are reused without changes; an existing disabled profile is rejected. Profile and subscription creation are atomic.- The master must be enabled and either public or owned by the same customer.
- The master
allowed_follower_modesmust allow the follower account mode (REALorDEMO) derived from the follower account group.
Enum Values¶
allowed_follower_modes¶
| Value | Name | Description |
| 0 | REAL_ONLY | Only REAL followers |
| 1 | DEMO_ONLY | Only DEMO followers |
| 2 | REAL_AND_DEMO | REAL and DEMO followers |
show_trade_history¶
| Value | Description |
|---|---|
0 |
Master trade history is private |
1 |
Master trade history can be viewed through GET /copytrade/master/trades |
show_followers¶
| Value | Description |
|---|---|
0 |
Master follower list and follower statistics are private |
1 |
Master followers can be viewed through GET /copytrade/master/followers |
manual_trading_mode¶
| Value | Name | Description |
| 0 | DISABLED | Manual trading is disabled |
| 1 | ALLOW_NON_COPIED | Manual trading is allowed except copied positions |
| 2 | ALLOW_ALL | Manual trading is allowed |
subscription status¶
| Value | Name |
|---|---|
0 |
ACTIVE |
1 |
PAUSED |
2 |
DISABLED |
copy_mode¶
| Value | Name |
|---|---|
0 |
FULL_SYNC |
1 |
OPEN_ONLY |
2 |
CLOSE_ONLY |
volume_mode¶
| Value | Name |
|---|---|
0 |
FIXED |
1 |
MULTIPLIER |
2 |
EQUITY_RATIO |
3 |
BALANCE_RATIO |
symbols_mode¶
| Value | Name |
|---|---|
0 |
ALL |
1 |
INCLUDE |
2 |
EXCLUDE |
reward_type¶
| Value | Name |
|---|---|
0 |
SUBSCRIPTION_FEE |
1 |
PERFORMANCE_FEE_HWM |
2 |
VOLUME_REBATE |
3 |
PROFIT_SHARE_PER_TRADE |
4 |
MANAGEMENT_FEE |
Detailed UI field behavior for each reward type is documented in CreateCopyTradeMaster.
Reward settlement¶
The runtime currently calculates and settles PROFIT_SHARE_PER_TRADE accruals.
Other reward types are configurable as policy values but their calculation and
settlement are not implemented. Settlement uses follower balance-out and master
payout balance-in operations with TR_REASON_COPY_REWARD; both carry
copy_reward_accrual_id in api_data.
Common Errors¶
| Error | Description |
|---|---|
INVALID_CUSTOMER_SESSION |
Customer session is missing or invalid |
INVALID_ACCOUNT |
Account login does not belong to the customer |
MASTER_ACCOUNT_MUST_BE_REAL |
Master profile can be created only on a REAL account |
REWARD_POLICY_REQUIRED |
Master creation request does not contain reward_policy |
INVALID_REWARD_POLICY |
Reward policy payload is invalid |
INVALID_PAYOUT_ACCOUNT |
Reward payout account is missing or not owned by the customer |
PERMISSION_DENIED |
Record exists but is not owned by this customer |
MASTER_NOT_FOUND |
master_login does not have a copy master profile |
MASTER_NOT_AVAILABLE |
Master is disabled/private and not owned by the customer |
TRADE_HISTORY_NOT_PUBLIC |
Master disabled public trade-history viewing |
FOLLOWERS_NOT_PUBLIC |
Master disabled public follower-statistics viewing |
FOLLOWER_NOT_FOUND |
follower_login does not have a copy follower profile |
FOLLOWER_MODE_NOT_ALLOWED |
Master does not allow follower REAL/DEMO mode |
RET_ERR_PARAMS |
Updated master and follower logins are the same account (HTTP 400) |
RET_ERR_DUPLICATE |
Updated master/follower pair already belongs to another subscription (HTTP 409) |