big-qmt/docs

QMT HTTP API

将迅投 QMT（MiniQMT / 投研版）策略进程内的 ContextInfo、行情、财务与交易函数，封装为 JSON HTTP 服务，供外部程序远程调用。

源码：api/QMT_API.py

完整接口清单、请求/响应字段与 curl 示例见 api.md。

---

1. 它是什么

QMT_API.py 不是可独立 python QMT_API.py 启动的普通脚本。它是一份 QMT Python 策略：

• QMT 加载策略后调用 init(ContextInfo)。
• init 绑定资金账号、加载股票池、创建 Tornado Application，并在当前进程里 listen + IOLoop.start()。
• 此后外部 HTTP 客户端通过 X-Token 鉴权，调用本机（或同网段）上的 REST 接口。
• 接口内部再转调 QMT 内置对象：ContextInfo.*、passorder、get_trade_detail_data 等。

因此：服务生命周期 = 策略生命周期。策略停止，HTTP 一并停止。

外部程序  --HTTP JSON-->  Tornado (0.0.0.0:10086)
                                |
                                v
                         QMT 策略进程
                         ContextInfo / 交易账户

---

2. 运行环境

项	要求
宿主	迅投 QMT（需启用 Python 策略）
解释器	QMT 自带的 Python（源码文件编码为 GBK）
第三方库	tornado（需在 QMT Python 环境中可用）
标准库	json / os / datetime / pathlib / logging / locale
操作系统	源码调用 locale.setlocale(locale.LC_CTYPE, 'chinese')，面向 Windows 中文环境

QMT 内置符号（由策略宿主注入，源码中未 import）：

• ContextInfo 及其方法（get_market_data、get_universe 等）
• 交易：passorder、algo_passorder、smart_algo_passorder、order_*、buy_open / sell_open 等
• 查询：get_trade_detail_data、get_value_by_order_id、can_cancel_order、cancel 等
• 其它：get_open_date、timetag_to_datetime、ext_data、get_etf_info 等

---

3. 配置

源码顶部与 init() 使用的配置如下。

名称	来源	默认值	说明
QMT_ACCOUNT_ID	环境变量	''	资金账号，写入 ContextInfo.accountID 并 set_account
QMT_DATA_DIR	环境变量	D:\qmt_strategy_data	意图上的数据目录；见下方「已知问题」
TOKEN	源码硬编码	QMTbyYanweidong	HTTP 鉴权口令，请求头 X-Token 必须与之相等
PORT	源码硬编码	10086	监听端口；绑定地址为 0.0.0.0

启动时还会读取：

{数据目录}/pass_codes.json

内容须为 JSON 数组（股票代码列表），用于 ContextInfo.set_universe(...)。该文件缺失或无法解析会导致 init 失败，HTTP 服务起不来。

---

4. 接入步骤

1. 在 QMT 中配置 Python 策略，入口文件指向 api/QMT_API.py。
2. 准备数据目录，放入 pass_codes.json，例如：

["000001.SZ", "600000.SH"]

3. 设置环境变量 QMT_ACCOUNT_ID（以及你实际使用的数据目录变量，见已知问题）。
4. 启动策略。日志出现类似：

QMT HTTP Server 启动于 http://0.0.0.0:10086 (全部API已加载)

5. 用任意 HTTP 客户端调用。所有业务接口默认需要鉴权：

X-Token: <与源码 TOKEN 一致>
Content-Type: application/json

快速探活（需 Token）：

curl -s -H "X-Token: QMTbyYanweidong" http://127.0.0.1:10086/api/context/period

关闭服务：

curl -s -X POST -H "X-Token: QMTbyYanweidong" http://127.0.0.1:10086/api/sys/shutdown

ShutdownHandler 会在响应后再 IOLoop.stop()，Tornado 事件循环退出。

---

5. 鉴权与协议约定

5.1 鉴权

BaseHandler.prepare()：

• 请求头 X-Token 必须等于源码中的 TOKEN。
• 否则抛出 HTTPError(401, "认证失败：token 无效或缺失")。
• 源码定义了 @no_auth 装饰器，但 没有任何 Handler 使用它，包括 /api/sys/python_version 与 /api/sys/shutdown。

5.2 请求

• GET：无 Body，参数都在路径中（本服务 GET 接口目前均无 Query）。
• POST：Body 必须是 合法 JSON 对象。多数 POST 一上来就 json.loads(self.request.body)，空 Body 会直接异常。
• 多标的字段（如 stock_code、stocks、stock_list、fieldList）一般为 逗号分隔字符串，服务端再 split(',') + strip()。

5.3 响应

• 默认 Content-Type: application/json; charset=utf-8。
• 成功：各接口自定义 JSON（见 api.md）。
• 失败：write_error 统一为：

{"error": "<reason>", "status_code": 401}

常见状态码：

码	场景
400	缺参、下单参数不合法
401	Token 缺失或错误
500	QMT 调用失败（部分接口在 safe_call 返回 None 后主动抛出）

safe_call 会吞掉底层异常并打日志，返回 None。调用方看到的可能是 null 字段，也可能是 500，取决于该 Handler 有没有对 None 再处理。

5.4 HTTP 方法习惯

• 只读、无参的 Context / 判定 / 系统信息：多数为 GET。
• 带 JSON Body 的查询与全部交易： POST。
• 同一资源没有 REST 语义上的 PUT/PATCH/DELETE。

---

6. 接口分组

路由在 make_app() 中注册，当前约 100+ 条。按前缀划分：

前缀	用途	文档
/api/v2/*	持仓 / 资产（与旧接口共用 Handler）	api.md §1
/api/holding /api/money/* /api/order/*	旧版买卖、资金、撤单、成交	同上
/api/context/*	策略上下文属性	§2
/api/data/*	行情、财务、期权、订阅	§3
/api/check/*	停牌、板块、K 线判定	§4
/api/trade/*	股票/算法/期货下单、任务、账户查询	§5
/api/ext/*	扩展数据与因子引用	§6
/api/sys/*	Python 版本、关停服务	§7

兼容层买卖是对 passorder 的薄封装：

• POST /api/order/buy → passorder(23, 1101, ...)（买入）
• POST /api/order/sell → passorder(24, 1101, ...)（卖出）
• 完整下单请用 POST /api/trade/passorder（可自定义 opType / orderType / prType / quickTrade）

账户查询里的 account 字段默认 "stock"，也会传到 get_trade_detail_data 的账户类型参数。

---

7. 回调与落盘（当前未挂接）

源码后半定义了主推回调，用于把账户/委托/成交/持仓写成 JSON 文件：

函数	意图文件名
account_callback	acount_%s.json（拼写为 acount）
order_callback	order_%s.json
deal_callback	deal_%s.json
position_callback	position_%s.json
orderError_callback	仅 print

init() 没有 调用 ContextInfo 的回调注册接口，因此这些函数默认不会执行。即便注册，write_json 本身也存在未定义变量问题（见下节），落盘路径目前不可靠。

---

8. 源码审视（使用前必读）

以下为对照 QMT_API.py 的事实，不是「建议优化清单」。接入前应按此理解行为边界。

8.1 数据目录变量不一致

DATA_DIR = os.environ.get('QMT_DATA_DIR', 'D:\\qmt_strategy_data')
# ...
Path(QMT_DATA_DIR) / "pass_codes.json"

环境变量读入的是 DATA_DIR，init / write_json 使用的是 从未赋值的 QMT_DATA_DIR。在普通 Python 里会 NameError。若你的 QMT 环境没有额外注入同名全局量，策略会在启动阶段失败。

8.2 write_json 不可用

• 使用未定义的 current.strftime（应为 now）。
• order_id 无默认值，但 account_callback / position_callback 只传了两个参数。
• file_key 模板与实参个数不一定匹配。

8.3 Token 硬编码且监听全网卡

TOKEN 写死在源码里；listen(..., address='0.0.0.0') 对所有网卡开放。任何能打到 10086 且知道 Token 的客户端都可以下单、撤单、关停服务。不要把该端口暴露到公网。

8.4 错误被吞掉

safe_call 捕获全部异常后返回 None。部分查询接口仍会把 null 当成功响应返回，调用方不易区分「没数据」和「QMT 抛错」。

8.5 编码

文件头 # -*- coding: gbk -*-。用 UTF-8 无 BOM 保存可能在 QMT 中出现中文注释/字符串解码问题。

8.6 规则撤单语义很窄

POST /api/order/cancel_order 不是「按委托号撤单」，而是：

• 股票代码（代码.市场）完全匹配，且
• m_nVolumeTotal + m_nVolumeTraded == volume，且
• can_cancel_order 为真

才发出 cancel。按委托号查询/判断请用 /api/trade/value_by_order_id、/api/trade/can_cancel_order。源码里没有单独的「按 orderId 撤单」HTTP 封装（全部撤单走 /api/order/cancel_all）。

---

9. 仓库结构

big-qmt/
├── api/
│   └── QMT_API.py      # QMT 策略 + HTTP 服务（唯一实现）
├── docs/
│   ├── README.md       # 本文件：架构、接入、约定、风险
│   └── api.md          # 全量 HTTP 接口说明
└── README.md           # 仓库占位

---

10. 相关文档

• HTTP API 参考
• 迅投 QMT Python 策略官方函数手册（passorder 的 opType / prType 等枚举以官方文档为准；本仓库只记录本封装实际传入的值）