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.push through EventBus;
the module must not be called from or embedded into the trading mainLoop.

Current implementation provides configuration, cache/storage and manager API methods. Runtime execution of copied trades is prepared through trade.push subscription, but copy execution is not enabled yet.

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.

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. Current public manager API exposes filter reads for links; links are expected to be created by runtime copy execution.

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

Current manager API exposes filter reads for accruals. Accrual creation is reserved for reward calculation 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
`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¶

CopyTradeManager runs as a separate event-driven module and does not add copy-trading branches to the main trading loop.

Runtime behavior:

subscribes to trade.push;
moves copy processing to the shared thread pool;
uses in-memory cache for masters, followers, subscriptions and trade links;
opens/closes follower trades through the normal Core trading API;
settles profit-share rewards through normal balance operations;
writes trade links through the CopyTradeManager DB strand/queue;
ignores follower orders already linked to copy trading to prevent recursive copying.

Currently supported:

market BUY/SELL open copy;
market close copy;
partial close copy by master partial-close ratio;
FIXED, MULTIPLIER, EQUITY_RATIO and BALANCE_RATIO volume modes;
min_volume, max_volume and max_positions;
ALL, INCLUDE, EXCLUDE symbol filters;
copy_sl and copy_tp;
reverse_direction for market trades;
copy_existing_positions when a subscription is created or updated;
active trade-link reconcile loop;
profit-share-per-trade reward accrual and settlement;
OPEN_ONLY, CLOSE_ONLY and normal open+close copy modes.

Current limitations:

pending orders are not copied;
SL/TP modification is not copied yet;
subscription fee, HWM performance fee, volume rebate and management fee execution are not implemented yet;
manual trading restrictions are not enforced by trade operations yet.

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.