big-qmt/docs/README.md

# QMT REST API 文档

当前实现：[`api/qmt_rest_new.py`](../api/qmt_rest_new.py)。完整接口、请求参数、返回字段及错误行为见 [API 参考](api.md)。更新日期：2026-09-07。

## 运行方式

文件运行在 QMT Python 策略宿主中，由宿主调用 `init(ContextInfo)` 并提供交易和查询内置函数，不能作为普通独立 HTTP 脚本启动。

启动流程：

1. 检查账户和数据目录配置非空，调用 `ContextInfo.set_account()`。
2. 从 `PASS_CODES_URL` 获取股票池，响应的 `data` 必须是数组。
3. 合并远端股票代码与账户当前持仓，去重后设置 `ContextInfo.set_universe()`。
4. 启动 Tornado，监听 `0.0.0.0:10086`。

远端请求超时为 10 秒，股票池请求、解析或持仓查询失败会阻止服务启动。当前不读取本地 `pass_codes.json`。

## 配置与依赖

| 配置 | 来源 | 默认 / 行为 |
| --- | --- | --- |
| `ACCOUNT_ID` | 环境变量 `QMT_ACCOUNT_ID` | 默认空，必须配置 |
| `DATA_DIR` | 环境变量 `QMT_DATA_DIR` | 默认 `D:\qmt_strategy_data`；当前只检查非空并记录日志，不读写目录 |
| `TOKEN` | 源码常量 | 请求头 `X-Token` 必须与其一致 |
| `PORT` | 源码常量 | `10086` |
| `PASS_CODES_URL` | 源码常量 | 远端股票池地址，见实现文件 |

源码编码为 UTF-8，依赖 `tornado`。启动时设置 `locale.LC_CTYPE` 为 `chinese`，需要环境支持该 locale。

## 接入

在 QMT 中配置账户环境变量并加载策略，启动后可用 PowerShell 查询：

```powershell
$apiHeaders = @{ 'X-Token' = '<服务端 TOKEN>' }
Invoke-RestMethod -Uri 'http://127.0.0.1:10086/api/context/info' -Headers $apiHeaders
```

当前没有 `/api/v2` 前缀，也没有 HTTP 关停路由。服务运行在策略进程中。

资产、持仓、委托、成交使用小写下划线字段；行情和原始查询保留 QMT 字段；下单请求仍用驼峰字段。

鉴权失败目前返回 HTTP 500，接口错误正文通常是文本，撤单失败可能返回 HTTP 200 并标记 `status=failed`。详见 [API 参考](api.md)。