Copy Trading API¶
The Copy Trading manager API is used by BackOffice to configure master strategies, follower accounts, copy subscriptions, trade links and reward policies.
This API belongs to the TCP manager layer. The desktop/web terminal also has a client REST layer for customer-owned copy trading records.
Architecture¶
Copy Trading is implemented as a separate CopyTradeManager module:
- separate SQLite database:
bases/copytrade.db; - separate structures and migrations;
- cache-first runtime model;
- database writes are synchronized through a strand-backed queue;
- runtime decisions are made from in-memory cache;
- the module subscribes to
trade.pushthroughEventBus; - the module must not be called from or embedded into the trading
mainLoop.
Runtime execution is active through the trade.push subscription. Copy opens,
updates, closes, pending-order synchronization and reward settlement are described
in Runtime Execution.
Roles¶
AccountRecord remains a regular trading account. Master/follower roles are
stored in Copy Trading entities and are not account types.
Entity Overview¶
Copy Master¶
Master describes an account strategy that followers can subscribe to. A master can be created only for a REAL account. DEMO accounts cannot become masters.
| Field | Type | Description |
|---|---|---|
id |
int | Master record id |
login |
int | Trading account login |
enabled |
int | 1 enabled, 0 disabled |
strategy_name |
string | Strategy display name |
description |
string | Strategy description |
visibility |
string | Visibility marker, for example private |
allowed_follower_modes |
int | Demo/real follower policy |
created_time |
int | Unix timestamp |
updated_time |
int | Unix timestamp |
Master creation also creates a reward policy. The reward policy is selected in
the same MngCreateCopyMaster / POST /copytrade/master request through
reward_policy.
Copy Follower¶
Follower describes an account that can copy a master.
The follower profile is created automatically with default settings when a customer or manager creates that account's first subscription. The defaults are enabled, manual trading allowed on non-copied orders, and one active master. An existing enabled profile is reused without modification, while an existing disabled profile blocks a new subscription. Profile and subscription creation are atomic. Standalone follower commands remain available for explicit preconfiguration, and a profile remains after its last subscription is removed.
| Field | Type | Description |
|---|---|---|
id |
int | Follower record id |
login |
int | Trading account login |
enabled |
int | 1 enabled, 0 disabled |
manual_trading_mode |
int | Manual trading policy |
max_master_count |
int | Maximum active masters allowed for the follower |
created_time |
int | Unix timestamp |
updated_time |
int | Unix timestamp |
Copy Subscription¶
Subscription connects one master to one follower.
| Field | Type | Description |
|---|---|---|
id |
int | Subscription id |
master_login |
int | Master account login |
follower_login |
int | Follower account login |
enabled |
int | 1 enabled, 0 disabled |
status |
int | Subscription status |
copy_mode |
int | Copy behavior |
volume_mode |
int | Volume calculation mode |
risk_multiplier |
double | Multiplier used by MULTIPLIER mode |
fixed_volume |
int | Fixed volume used by FIXED_VOLUME mode |
copy_sl |
int | Copy stop loss flag |
copy_tp |
int | Copy take profit flag |
copy_partial_close |
int | Copy partial close flag |
copy_pending_orders |
int | Copy pending orders flag |
copy_existing_positions |
int | Copy existing positions flag |
reverse_direction |
int | Reverse trade direction flag |
max_volume |
int | Maximum copied volume, 0 means not configured |
min_volume |
int | Minimum copied volume, 0 means not configured |
max_positions |
int | Maximum copied positions, 0 means not configured |
symbols_mode |
int | Symbol filter mode |
symbols |
string | Symbol filter payload |
created_time |
int | Unix timestamp |
updated_time |
int | Unix timestamp |
Copy Trade Link¶
Trade link maps master order to follower order.
| Field | Type | Description |
|---|---|---|
id |
int | Link id |
subscription_id |
int | Subscription id |
master_login |
int | Master account login |
follower_login |
int | Follower account login |
master_order |
int | Master order id |
follower_order |
int | Follower order id |
state |
int | Link state |
created_time |
int | Unix timestamp |
updated_time |
int | Unix timestamp |
Trade links are runtime mapping records. The manager API exposes filtered reads for links created and maintained by runtime copy execution. A FAILED link (state = 2) is retained as a diagnostic record when an attempted copy fails; it does not indicate a successful follower copy.
Copy Reward Policy¶
Reward policy describes how a master should be rewarded.
| Field | Type | Description |
|---|---|---|
id |
int | Reward policy id |
master_id |
int | Copy master id |
enabled |
int | 1 enabled, 0 disabled |
reward_type |
int | Reward model |
billing_period |
string | Billing period marker |
fee_amount |
double | Fixed fee amount |
fee_percent |
double | Percent fee |
currency |
string | Fee currency |
payout_account_login |
int | Master payout account login |
hwm_enabled |
int | High-water mark flag |
created_time |
int | Unix timestamp |
updated_time |
int | Unix timestamp |
Copy Reward Accrual¶
Reward accrual is a calculated reward record.
| Field | Type | Description |
|---|---|---|
id |
int | Accrual id |
subscription_id |
int | Subscription id |
master_login |
int | Master login |
follower_login |
int | Follower login |
reward_type |
int | Reward type |
period_from |
int | Period start timestamp |
period_to |
int | Period end timestamp |
base_amount |
double | Calculation base amount |
fee_amount |
double | Fee amount |
currency |
string | Fee currency |
state |
int | Accrual state |
created_time |
int | Unix timestamp |
updated_time |
int | Unix timestamp |
The manager API exposes filtered reads for reward accruals created by reward calculation and settlement runtime.
Enum Values¶
allowed_follower_modes¶
| Value | Name | Description |
|---|---|---|
0 |
REAL_ONLY | Only real follower accounts |
1 |
DEMO_ONLY | Only demo follower accounts |
2 |
REAL_AND_DEMO | Real and demo follower accounts |
manual_trading_mode¶
| Value | Name | Description |
|---|---|---|
0 |
DISABLED | Manual trading is disabled for follower |
1 |
ALLOW_NON_COPIED | Manual trading allowed only for non-copied positions |
2 |
ALLOW_ALL | Manual trading allowed for all positions |
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 |
trade link state¶
| Value | Name |
|---|---|
0 |
active |
1 |
closed |
2 |
failed |
3 |
cancelled |
reward_type¶
| Value | Name |
|---|---|
0 |
subscription_fee |
1 |
performance_fee_hwm |
2 |
volume_rebate |
3 |
profit_share_per_trade |
4 |
management_fee |
reward accrual state¶
| Value | Name |
|---|---|
0 |
pending |
1 |
charged |
2 |
paid |
3 |
failed |
4 |
cancelled |
Table Filter Methods¶
All MngGet*ByFilter methods return table-style responses:
{
"structure": ["id", "login", "enabled"],
"rows": [
[1, 2000001, 1]
],
"count": 1
}
They accept the standard table filter payload:
| Name | Type | Required | Description |
|---|---|---|---|
limit |
int | Yes | Page size |
offset |
int | Yes | Page offset |
where |
array | No | Include filters |
orWhere |
array | No | OR comparison group in [[field, operator, value], ...] format; at least one condition must match |
whereNot |
array | No | Exclude filters |
whereIn |
array | No | Include by values |
whereNotIn |
array | No | Exclude by values |
whereBetween |
array | No | Range filters |
whereNotBetween |
array | No | Negative range filters |
orderBy |
array | No | Sort definition |
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 field accepts integers >= 1 and defaults to 1. The limit
counts distinct master logins. Create/update/resume and lowering the follower
limit enforce the bound; excess returns RET_TRADE_LIMIT_REACHED (HTTP 409).
When MngUpdateCopySubscription changes either account login, the resulting
master and follower must be different accounts (RET_ERR_PARAMS), and the pair
must not belong to another subscription (RET_ERR_DUPLICATE). Duplicate
detection excludes the subscription being updated. Existing subscriptions with
unchanged logins remain editable, including historical records that would fail
these checks if relinked.
Reward settlement uses two balance operations with TR_REASON_COPY_REWARD:
OP_BALANCE_OUT from follower and OP_BALANCE_IN to master payout account.
Both operations carry copy_reward_accrual_id in api_data.
Manager Access And Permissions¶
Manager copytrade endpoints are available to SESSION_MANAGER, SESSION_ADMIN, SESSION_DEALER, SESSION_CRM_MANAGER and SESSION_CRM_ADMIN. Non-admin managers must have either access_backoffice or access_crm; concrete operations also require one of these permissions:
| Permission | Applies To |
|---|---|
see_copytrade |
Manager read operations: masters, followers, subscriptions, trade links, reward policies, reward accruals, master stats, master trades and master followers |
set_copy_masters |
MngCreateCopyMaster, MngUpdateCopyMaster |
del_copy_masters |
MngDeleteCopyMaster |
set_copy_followers |
MngCreateCopyFollower, MngUpdateCopyFollower |
del_copy_followers |
MngDeleteCopyFollower |
set_copy_subscriptions |
MngCreateCopySubscription, MngUpdateCopySubscription; copy_existing_positions execution is covered by this permission because it is part of subscription configuration |
del_copy_subscriptions |
MngDeleteCopySubscription |
set_copy_rewards |
MngCreateCopyRewardPolicy, MngUpdateCopyRewardPolicy |
del_copy_rewards |
MngDeleteCopyRewardPolicy |
SESSION_CUSTOMER and SESSION_USER copytrade marketplace/self-service endpoints keep their own customer/user visibility rules and do not use manager permissions.