Simulated trading platform: configuration and operation

This chapter guides you from “existing backtesting strategies” to “the first stable startup of a simulated live trading account”: which items to configure, how to confirm them, and what to look for after startup.

Dear user, if you already have an Operator (trader container) that can backtest, this chapter is the shortest path to live testing. We’ll first explain the necessary configurations, and then discuss optional advanced features such as “strategy snapshots” and “startup access control.”

0. 适用场景

You have a working Operator and are ready to move from backtesting to live simulation.
You want to first test the shortest path before gradually adding risk control, access control, and operational details.

1. 核心概念（本章术语）

Before starting Live, please confirm the relationship between the three components. In Qteasy, the Operator is responsible for “calculating signals,” the Live account is responsible for “keeping accounts and positions,” and the local data source is responsible for “providing prices and historical data”—without any one of these, the Trader cannot run stably. The table below illustrates the position of each component in the Live subsystem and what you need to prepare.

The meaning of each column: Role is the component name; Function is the responsibility in the live pipeline; What you need to prepare are the pre-launch checks.

How to use: Check the boxes one by one; if a column is insufficient, add the data or account information first, then run qt.run(op).

Role	effect	What do you need to prepare?
Operator	Holding strategy and signal logic	Same `op` object as during backtesting
live account	Record cash, holdings, and orders.	`live_trade_account_id` or `live_trade_account_name`
Local data source	Provides historical and real-time quotes	Table data coverage strategy frequency (e.g., minute-based strategy requires minute-based tables)

LiveTradeConfig (live configuration snapshot): Before starting Trader, qteasy verifies and freezes the live-related items scattered throughout qt.configure(...) into an immutable snapshot—like a checklist signed before takeoff—to prevent accidental configuration changes during runtime. You can view a summary using liveconfig in the shell.

2. 最小配置集

The following are common essential configuration items (failure to set or incorrect setting will often result in errors during startup). These keys are written to the global configuration via qt.configure(...) and are incorporated into the LiveTradeConfig snapshot at startup; they determine “whether it is live, what assets are traded, which account is used, where the price comes from, and who matches the orders.”

Meaning of each column: The configuration key is the name in QT_CONFIG; meaning is the behavior controlled by this key; what happens if it is not set are common consequences (to help determine whether the current error is related to this key).

How to use: For your first live session, please explicitly set all settings; if startup fails, check the “What happens if I don’t set anything” column for troubleshooting. See §5 Template A/B for examples.

Configuration key	Meaning	What would happen if we didn’t set one?
`mode=0`	Enter live/demo trading	Still using backtesting or other modes
The set of names of the historical data to be fetched, if htypes is empty, the system will try to create all possible htypes by basing on the name of the historical data and the freq/asset_type parameter. the input can be str or list: - str: ‘open, high, low, close’ - list: [‘open’, ‘high’, ‘low’, ‘close’] - list: [‘open’, ‘high’, ‘low’, ‘close’] - list: [‘open’, ‘high’, ‘low’, ‘close’] ‘high’, ‘low’, ‘close’]	Asset types, such as E-shares and F-shares (ETFs).	The trading rules and data tables may not match.
`live_trade_account_id` or `live_trade_account_name`	Which demo account to use?	Unable to bind ledger
`live_trade_broker_type`	Brokerage firm types, beginners use `simulator`	No transaction channel
`live_price_acquire_channel`	Real-time pricing channels, such as `eastmoney`	Unable to obtain live price
`live_price_acquire_freq`	Price increase frequency, such as `15MIN`	Data may be missing when the pace of the strategy is not coordinated.

The following keys are not hard requirements for startup, but it is strongly recommended to confirm them—they affect the minimum transaction unit, log writes to disk, and disk usage. They belong to the qt.configure scope along with the table above and can be written to the same script.

How to use: If the transaction quantity is not “in complete lots” or the log file cannot be found, go back and check the corresponding row in this table.

Configuration key	Meaning	What would happen if we didn’t set one?
`trade_batch_size` / `sell_batch_size`	Minimum unit of sale	Use default values
`cash_decimal_places` / `amount_decimal_places`	Cash/Quantity Decimal Places	Use default values
`sys_log_file_path` / `trade_log_file_path`	System/Transaction Log Directory	Use the default path within the package
`trade_log_keep_days`	Log retention days (including risk logs)	Automatic cleanup every 3 days by default

3. 查看配置快照

Python (self-checking in the script):

from qteasy.live_config import build_live_trade_config
import qteasy as qt

cfg = build_live_trade_config(qt.QT_CONFIG)
print(cfg.to_summary_dict())

CLI (Trader Shell): Command liveconfig (alias live-config)

Default: stable field subset
Add --detail: additionally includes keys for enabling access control, policy snapshots, etc.

Note: The liveconfig in the Shell is a summary based on the current Trader, not a memory reference of the object at startup—but it’s sufficient for you to check “the configuration that is currently in effect”.

4. 配置键分组（主要 live 键）

There are many configuration keys related to Live. For easy reference, we have grouped them by function (not a full API list; complete fields are based on LiveTradeConfig). In qteasy, these keys are validated and frozen before startup—you need to restart the Live process after modifying qt.configure for the changes to take effect.

Column Meanings: Grouping represents the responsibility domain within the live subsystem; Representative Keys list the most frequently modified keys in this group (there may be other keys in the same group that are not listed); Descriptions describe the role of this group during operation.

How to use: Select the group according to your current task—for example, to troubleshoot log issues, look at the “Log” line and jump to: :doc:5-artifacts-and-troubleshooting; when opening a minute-by-minute strategy, first check if the “Market Data and Refill” matches the strategy’s frequency.

Example: Sub-daily frequency strategies often modify live_price_acquire_freq in the “Market Data and Refill” group, and enable live_trade_split_strategy_prepare in the “Strategy Snapshots (5-A)” group as needed.

Grouping	Representative key	Description
Accounts and UI	`live_trade_account_id`, `live_trade_account_name`, `live_trade_ui_type`	Account and CLI/TUI selection
Market conditions and refill	`live_price_acquire_channel`, `live_price_acquire_freq`, `live_trade_data_refill_channel`, `live_trade_*_refill_tables`	Real-time price and timed data updates
Trading Rules	`trade_batch_size`, `sell_batch_size`, `stock_delivery_period`, `cash_delivery_period`, `pt_buy_threshold`, `pt_sell_threshold`	Align with backtesting semantics
Broker	`live_trade_broker_type`, `live_trade_broker_params`	The default is `simulator`; see `doc:`4-broker-adapter-and-integration` for extensions.
Strategy Snapshot (5-A)	`live_trade_split_strategy_prepare`, `live_trade_prepare_lead_seconds`, `live_trade_strategy_snapshot_max_age_seconds`	Data is pre-fetched before the strategy runs; see :doc:`6-trader-snapshot-gate` for details.
Activate access control (5-B)	`live_trade_startup_gate_mode` (`off` / `warn` / `block`)	Pre-market security check; CLI `gate`
log	`sys_log_file_path`, `trade_log_file_path`, `trade_log_keep_days`	Includes `*.risk.log` rotation; see:doc:`5-artifacts-and-troubleshooting`

The complete fields are based on LiveTradeConfig; the valid values for each key are defined in the configuration validation logic.

5. 推荐配置模板

Template A: Stocks (E+ Simulated Brokerage)

The following code executes before qt.run(op), telling qteasy to use stock rules, Eastmoney 15-minute price, and simulated counter trading.

import qteasy as qt

qt.configure(
    mode=0,
    asset_type='E',
    live_trade_broker_type='simulator',
    live_price_acquire_channel='eastmoney',
    live_price_acquire_freq='15MIN',
    trade_log_keep_days=3,
)

Template B: Exchange-Traded Funds / ETFs (FD + Simulated Brokerage)

Same as template A, except that asset_type='FD' applies to example paths such as ETF.

import qteasy as qt

qt.configure(
    mode=0,
    asset_type='FD',
    live_trade_broker_type='simulator',
    live_price_acquire_channel='eastmoney',
    live_price_acquire_freq='15MIN',
    trade_log_keep_days=3,
)

Template C: Policy Snapshot + Activate Access Control (Smoke/Advanced)

Consistent with :doc:7-manual-smoke-live-grid-roadmap; it is recommended to open this after you are familiar with template A/B.

qt.configure(
    live_trade_split_strategy_prepare=True,
    live_trade_prepare_lead_seconds=60,
    live_trade_strategy_snapshot_max_age_seconds=300.0,
    live_trade_startup_gate_mode='warn',  # 先 warn 观察，稳定后可试 block
)

6. 启动流程（分步说明）

Complete the configuration: Follow §2 to complete qt.configure(...), and confirm the account ID/name.
(Optional) Check Snapshot: Run the Python snippet in §3, or execute liveconfig --detail in the Shell after startup.
Startup: qt.run(op); Common command-line examples use --ui cli to enter the Trader Shell.
Observation: Check whether the status, orders, and logs are written as expected (§7).

Print several key configuration items quickly before startup:

import qteasy as qt

for key in ('mode', 'asset_type', 'live_trade_broker_type',
            'live_price_acquire_channel', 'live_trade_startup_gate_mode'):
    print(key, qt.get_config(key)[key])

7. 启动后建议先看什么（CLI）

Once you enter the Trader Shell, the following commands will help you confirm whether the configuration is effective, where the logs are located, whether the brokerage firm can process your request, and whether access control is successful. These correspond to the operations subset in :doc:8-cli-trader-capability-matrix—not all Shell commands.

Meaning of each column: Command: The name entered at the prompt (see the Matrix chapter for aliases); Typical Uses: The questions most frequently resolved by this command.

How to use: After starting, quickly scan the table from top to bottom; if a step is abnormal, redirect the output of the command to :doc:5-artifacts-and-troubleshooting.

Example: Unsure of the log path → Enter artifacts → Open the returned sys_log path to view the startup trace.

The command	Typical use cases
`liveconfig`	Current live configuration summary
`artifacts`	Four-bond product path (where are the logs located)
`gate`	Manually run the access control system once (for debugging).
`broker status`	Is the simulated brokerage firm “connected”?
`reconcile`	Reconciliation Snapshot JSON
`run --task diagnose_pending_orders`	Diagnostic in transit (requires DEBUG mode)

For the complete set of commands, see :doc:8-cli-trader-capability-matrix.

7.1 Dashboard and Interactive Mode

Trader Shell starts in dashboard mode by default: a single-line status area scrolls to display the countdown to the next task, real-time prices in the monitoring list, and system messages, allowing you to observe the operational rhythm without entering commands. To manually place orders, check configurations, or execute maintenance commands, press Ctrl+C to open the mode menu, or type dashboard in interactive (command) mode to return to the dashboard.

Mode	Behavior
dashboard	The status row and monitored price are automatically refreshed; the Trader main loop continues to run in the background.
interactive (command)	The traditional `Cmd` prompt allows you to enter commands such as `buy`, `config`, and `artifacts`.

Ctrl+C mode selection menu (available in both dashboard and command mode)

Within 5 seconds, press 1 → to enter command mode; 2 → to return to the dashboard; 3 → to exit and stop Trader.
No need to press Enter, the number keys take effect immediately.
No input within 5 seconds → Automatically resume the mode before the interruption.
Press Ctrl+C again during the menu wait time → Exit immediately (equivalent to selecting 3)

If an unexpected exception occurs in the main loop, the Shell will prompt you to press 1 to return to the dashboard or 3 to exit; if there is no input for 5 seconds, it will return to the dashboard by default, and the Trader will continue running.

8. 运行前检查清单

Account ID/name is available and matches the strategy asset pool.
asset_type should be consistent with asset_pool (do not mix rules for stocks and funds).
live_trade_broker_type should be simulator (or a type you have already implemented).
Live price frequency no less than the strategy’s running frequency (minute-based strategies require sufficiently frequent live prices).
Log path is valid and disk is writable.
trade_log_keep_days meets your retention expectations (including risk logs).

9. 常见启动失败与处理

When errors occur during startup, the symptoms often fall into a few categories: configuration, account, data, path, frequency, or startup access control. The table below is indexed by the symptoms you observe to avoid blindly searching the logs.

Explanation of each column: Phenomenon: The behavior during startup or on the first screen; Possible Causes: Common root causes (not exhaustive); Suggestions: The next steps.

How to use: First, match the “phenomenon” column; if the problem persists, use the §7 command to export the paths to liveconfig and artifacts, and refer to the decision tree in :doc:5-artifacts-and-troubleshooting.

Phenomenon	Possible reasons	suggestion
Configuration verification failed.	A certain live key is invalid or mutually exclusive.	After correcting the error messages, restart.
Account unavailable	ID/name incorrect or not initialized	Check account creation parameters
Data unavailable	Channel/Frequency/Local Table Missing	Check the refill and `stock_1min` tables, etc.
Path error	The log directory is not writable	Check `sys_log_file_path` etc.
Frequency incoordination	Live cost-effectiveness strategy with higher step frequency is rarer	Increase `live_price_acquire_freq` or decrease the policy frequency.
gate block	Access control `block` is activated but the check fails.	See the `gate` output and the `failures` section in the trace.

10. 相关跳转

Risk Control and Orders: 3-risk-and-order-lifecycle
Products and Troubleshooting: :doc:5-artifacts-and-troubleshooting
Broker adaptation: :doc:4-broker-adapter-and-integration
Snapshot/Access Control: :doc:6-trader-snapshot-gate
Smoke List: :doc:7-manual-smoke-live-grid-roadmap
CLI Reference: :doc:8-cli-trader-capability-matrix
Full walkthrough: tutorials/8-live-trade-risk-and-broker-walkthrough.md

11. 最小验收标准

Stable startup is possible under E or FD path
The output of liveconfig / artifacts is as expected.
At least one of the following can be observed: order submission, risk control rejection, or counter processing.
If risk control rejects the order: a record can be found in the risk_log; if the broker rejects the order: the order is marked as rejected and the broker number is empty.
The corresponding runtime artifacts can be found in the log directory.