Brokerage Adaptation Layer and Integration

This chapter is for users and developers who are preparing to connect to a new brokerage firm (or QMT in the future): What does the “Unified Counter Interface” layer above the simulated brokerage firm look like and how can it be expanded?

Reader’s Note: If you are new to simulated trading, you only need to read sections :doc:2-configuration-and-run and :doc:3-risk-and-order-lifecycle; this chapter can be skipped for now. Return to this chapter when you need to connect to a real trading platform or a custom broker.

Dear users, in qteasy, the Broker is responsible for “accepting orders → informing you whether to accept them → asynchronously pushing out the execution.” The default simulator uses live prices to simulate all of this; we have designed a unified adaptation layer so that when switching to real trading platforms such as QMT in the future, the main logic of the Trader will not need to be changed as much as possible.

0. 适用场景

You want to integrate with the new brokerage firm while maintaining compatibility with the existing Trader logic.
You need to first establish the minimum closed loop of “Submission → Acceptance Result → Transaction Response → Status Update”.

1. 核心概念：分层结构

Typical live call chain (from outside to inside):

Operator.run_live_trade()
  → Trader（日程、风控、账本）
       → BrokerFacade（券商适配外壳：统一 API）
            → SimulatorBroker / 您注册的 Broker

BrokerFacade (Adaptive Shell): Like a unified translation layer for different brokerage counters—Traders only need to say “connect / submit / poll_fills” to the Facade, without needing to care whether the underlying layer is analog or QMT.

Key points:

Facade provides external connections such as connect, disconnect, submit with ack, poll fills, and get remotely.
In the CLI, broker status|connect|disconnect reflects is_connected (in the simulator, this means “the adapter layer is ready”, not a real brokerage login).
The Trader main loop consumes trade rewards via poll_fills, instead of directly accessing the internal queue.

2. 核心接口（用户/开发者向）

The Broker Adaptation Layer serves as the unified interface between Trader and specific brokerages (simulators, and future QMT, etc.). Regardless of the underlying layer, Trader uses the same process: “Connect → Submit Order → Listen for Acceptance → Poll for Execution → Check Remote Ledger if necessary.” The table below provides a comparison of interface names and daily usage for easy reference when reading the comparison table and integration list below.

Meaning of each column: Interface is the name of the adaptation layer method; What to do is the responsibility in the live link; You can think of it as a metaphor to help you remember.

How to use: When integrating a new brokerage, implement each item in the checklist in §6; for daily operations and maintenance, you only need to focus on connect, submit_with_ack, poll_fills, and the CLI broker status.

Interface	do what	You can understand it as
`connect` / `disconnect`	Establish/disconnect adaptation layer session	Counter window opening/closing
`is_connected`	Have you connected?	Is the window open?
`submit_with_ack`	Submit the order and simultaneously receive confirmation of acceptance or rejection.	Listen for “Accept/Reject” immediately after submitting the order.
`cancel`	Cancel	Cancel unexecuted orders
`poll_fills`	Receive asynchronous transaction feedback	Ask “Any new transactions?”
`get_remote_*`	View remote cash/positions/orders	Reconcile accounts with brokerage firms’ ledgers (simulators are mostly placeholders).

2.1 Interface Responsibilities Comparison

The same interface behaves differently in the simulator and the real QMT: the former uses live pricing for simulation, while the latter connects to the front-end. The table below helps you establish expectations—avoiding mistaking the connect on the simulator for a real login, and also facilitating the planning of additional capabilities when integrating with QMT.

The meaning of each column: Interface is the same as §2; Semantics is the abstract responsibility; On the simulator you will see is the current default simulation behavior; Real QMT (planned) is a future goal (not a commitment in the current version).

How to use: When troubleshooting, first check if the simulator column meets the “acceptance + report” criteria; when planning QMT, select the target capabilities in the last column.

Interface	Semantics	On the simulator you will see	Real QMT (under planning)
`connect` / `disconnect`	The session	Internal flag set; not a genuine login.	Real login and reconnection
`submit_with_ack`	Simultaneous processing	Returns accepted, simulates broker_order_id, etc.	柜台真实受理结果（见 :doc:`4a-xtquant-broker-adapter-contract-v1`）
`poll_fills`	Asynchronous rewards	Simulated transaction queue	Real transaction push/polling
`get_remote_*`	Remote Ledger	Usually empty or None	Data source for reconciliation, access control, and synchronization
`cancel`	Cancel	Simulation implementation	Real cancellation number mapping

It is recommended to understand the priority based on the “smallest closed loop”:

Connection: connect / is_connected
Transaction: submit_with_ack / cancel
Reward: poll_fills
Query: get_remote_* (Only has full business significance after being connected to a real counter)

3. submit_with_ack 与本地订单

Unlike risk control order rejection: Risk control is prioritized and is not included in the order list (see :doc:3-risk-and-order-lifecycle).

submit_with_ack synchronously returns whether the brokerage firm has accepted the order. The table below only describes the correspondence between local orders and broker_order_id during the acceptance stage; for transaction progress, see the status table in :doc:3-risk-and-order-lifecycle.

Meaning of each column: Accepted result: This corresponds to the accepted semantics in ACK; Local order: This indicates the status of the order table; broker_order_id: This indicates whether the brokerage order number has been written back.

How to use:: If an order is rejected and the broker number is empty, check the row with “accepted=False”; if there is a broker number but the transaction has not been completed for a long time, check the status table and poll_fills.

Acceptance results	Local orders	broker_order_id
`accepted=True`	Continue to circulate	Rewrite back brokerage firm number and name
`accepted=False`	Often `rejected`	Keep empty

For detailed comparison, see :doc:6-trader-snapshot-gate.

Before submission, the order structure and reward fields are validated under contract. If the format is incorrect, an error will be reported as soon as possible to avoid “dirty data entering the ledger”.

4. 扩展新 Broker 类型

XtQuant / MiniQMT：配置项 live_trade_broker_type='xtquant' 已在 2.5.2 白名单中；实现细节与禁止双重下单等规则见英文契约 :doc:4a-xtquant-broker-adapter-contract-v1（协作方 PR 评审基准）。

Register a factory (example):

from qteasy.broker import register_broker_factory

register_broker_factory('my_broker', MyBrokerFactory)
# qt.configure(live_trade_broker_type='my_broker')

独立扩展包（推荐用于 QMT）：

import qteasy_xtquant

qteasy_xtquant.register()
# qt.configure(live_trade_broker_type='xtquant')

CLI sync (alias pull-state): Currently reserved, execution will print [NOT_IMPLEMENTED] ..., indicating that the actual “pull state from brokerage” has not yet been implemented; it will be replaced with an available implementation after integration with QMT.

5. 边界行为（接入时请注意）

Submitting or polling without connecting should result in an explicit error, not a silent failure.
cancel Unknown delegation number: Should consistently return “Cancelled”.
poll_fills timeout: An empty list should be returned, not dirty data.
On the simulator, **connect does not represent a real brokerage session; it only indicates that the adaptation layer can handle it.

6. 最小接入清单

Implement connect / disconnect / is_connected
Connect submit_with_ack to poll_fills
The return field satisfies the contract validation.
Implement cancel and exception paths
(If access control/reconciliation/sync is required) Implement get_remote_*
Verify the following in the CLI: broker status, reconcile, and order mapping.

7. 最小验收标准

is_connected=True after connect, can be submit_with_ack
Successfully processed: Local order contains broker_order_id
Order rejection: rejected and the broker field is empty.
poll_fills returns are verifiable.
Not connected / Unknown order / Timeout behavior is stable
CLI broker / reconcile observable

8. 相关跳转

Lifecycle and Risk Control: 3-risk-and-order-lifecycle
Products and Troubleshooting: :doc:5-artifacts-and-troubleshooting
Snapshot/Access Control: :doc:6-trader-snapshot-gate
CLI Reference: :doc:8-cli-trader-capability-matrix
Design Description: design/10-live-trading-s1.3-architecture.md