big-qmt/docs/api.md

# QMT REST API 参考

根据 [`api/qmt_rest_new.py`](../api/qmt_rest_new.py) 的路由、Handler 和格式化函数重新生成。更新日期：2026-09-07。启动说明见 [README.md](README.md)。

## 1. 公共约定

- Base URL：`http://<host>:10086`，监听 `0.0.0.0`。
- 所有已注册接口均要求 `X-Token: <服务端 TOKEN>`，没有免鉴权接口。
- POST 请求体为 JSON 对象，使用 `Content-Type: application/json`。
- 账户取自服务端 `QMT_ACCOUNT_ID`，账户类型固定为 `stock`，请求不能切换账户。
- 成功响应没有统一包装，具体形状见各接口。
- 资产、持仓、委托、成交字段为小写下划线；下单请求仍使用驼峰字段；行情及原始查询保留 QMT 字段。
- 字段类型按 QMT 属性约定列出；除资产金额四舍五入外，格式化函数不强制类型转换、不填默认值、不转换枚举和日期。
- 枚举含义、原始日期格式、行情和其他透传结果由 QMT 决定，本文件不扩展源码未定义的契约。

## 2. 接口清单

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| GET | `/api/context/info` | 策略上下文 |
| GET | `/api/get/{handler_type}` | 单证券查询 |
| GET | `/api/portfolio` | 聚合资产、持仓、委托 |
| GET | `/api/portfolio/assets` | 资产 |
| GET | `/api/portfolio/positions` | 持仓 |
| GET | `/api/portfolio/order` | 委托数组 |
| GET | `/api/portfolio/deal` | 成交数组 |
| GET | `/api/portfolio/org/{handler_type}` | 原始记录 |
| POST | `/api/data/full_tick` | 实时行情 |
| POST | `/api/trade/passorder` | 下单 |
| POST | `/api/trade/cancel_by_id` | 撤单 |
| POST | `/api/trade/ipo_data` | 发行数据 |
| GET | `/api/sys/python_version` | Python 版本 |

## 3. 策略上下文

`GET /api/context/info`，无参数，返回以下对象字段：

| 字段 | 来源 |
| --- | --- |
| `period` | `ContextInfo.period` |
| `barpos` | `ContextInfo.barpos` |
| `time_tick_size` | `ContextInfo.time_tick_size` |
| `stockcode` | `ContextInfo.stockcode` |
| `dividend_type` | `ContextInfo.dividend_type` |
| `market` | `ContextInfo.market` |
| `do_back_test` | `ContextInfo.do_back_test` |
| `benchmark` | `ContextInfo.benchmark` |
| `capital` | `ContextInfo.capital` |
| `timetag` | `ContextInfo.timetag` |
| `universe` | `ContextInfo.get_universe()` |

属性按原值输出；`stockcode` 是此接口的实际字段名。

## 4. 单证券查询

`GET /api/get/{handler_type}?stock_code=600000.SH`

`stock_code` 为必填 Query 字符串，去除首尾空格后不能为空，整体传入底层函数，不拆分逗号。

| handler_type | 调用 |
| --- | --- |
| `stock_name` | `ContextInfo.get_stock_name(stock_code)` |
| `open_date` | `ContextInfo.get_open_date(stock_code)` |
| `last_volume` | `ContextInfo.get_last_volume(stock_code)` |
| `total_share` | `ContextInfo.get_total_share(stock_code)` |
| `svol` | `ContextInfo.get_svol(stock_code)` |
| `bvol` | `ContextInfo.get_bvol(stock_code)` |
| `divid_factors` | `ContextInfo.get_divid_factors(stock_code)` |
| `etf_info` | 全局 `get_etf_info(stock_code)` |
| `etf_iopv` | 全局 `get_etf_iopv(stock_code)` |
| `instrumentdetail` | `ContextInfo.get_instrumentdetail(stock_code)` |
| `his_st_data` | `ContextInfo.get_his_st_data(stock_code)` |

响应示例：

```json
{"stock_code":"600000.SH","ref":"示例证券名称"}
```

`ref` 透传底层结果，可为字符串、数值、对象、数组或 null；无法直接序列化的值通过 `str()` 转换。缺失或空代码返回 HTTP 500；不支持的路径类型通常因路由不匹配返回 404。

## 5. 账户查询

以下接口均无请求参数。

### 5.1 聚合快照

`GET /api/portfolio`

依次调用 `get_trade_detail_data(account_id, 'stock', 'account' / 'position' / 'order')`，分别格式化为以下三个字段：

```json
{
  "assets":{"total":100000.0,"available":30000.0},
  "positions":{},
  "orders":[]
}
```

不包含成交。三次底层查询顺序执行，不保证同一时刻的原子快照；资产为空时整个请求失败。

### 5.2 资产

`GET /api/portfolio/assets`，查询 `account`，仅使用第一条记录。

| 字段 | JSON 类型 | QMT 来源 / 转换 |
| --- | --- | --- |
| `total` | number | `m_dBalance，round(..., 2)` |
| `available` | number | `m_dAvailable，round(..., 2)` |

```json
{"total":100000.0,"available":30000.0}
```

`total` 来源为账户余额字段，客户端作为总资产使用；`available` 为可用资金。无账户数据返回 HTTP 500。四舍五入不保证 JSON 文本固定显示两位小数。

### 5.3 持仓

`GET /api/portfolio/positions`，查询 `position`。

返回以证券代码为 key 的对象，每个 value 包含下表全部字段。空结果为 `{}`；同一代码多条记录以后面的覆盖前面的，不合并数量。

| 字段 | JSON 类型 | QMT 来源 / 转换 |
| --- | --- | --- |
| `stock_code` | string | `m_strInstrumentID + "." + m_strExchangeID` |
| `stock_name` | string | `m_strInstrumentName` |
| `direction` | integer | `m_nDirection` |
| `volume` | integer | `m_nVolume` |
| `open_price` | number | `m_dOpenPrice` |
| `open_cost` | number | `m_dOpenCost` |
| `float_profit` | number | `m_dFloatProfit` |
| `market_value` | number | `m_dMarketValue` |
| `stock_holder` | string | `m_strStockHolder` |
| `frozen_volume` | integer | `m_nFrozenVolume` |
| `can_use_volume` | integer | `m_nCanUseVolume` |
| `on_road_volume` | integer | `m_nOnRoadVolume` |
| `yesterday_volume` | integer | `m_nYesterdayVolume` |
| `last_price` | number | `m_dLastPrice` |
| `profit_rate` | number | `m_dProfitRate` |
| `future_trade_type` | integer | `m_eFutureTradeType` |
| `expire_date` | string | `m_strExpireDate` |

`volume` 为持仓数量，`can_use_volume` 为可用数量，`frozen_volume` 为冻结数量，`on_road_volume` 为在途数量，`yesterday_volume` 为昨日数量。`open_price`、`open_cost`、`float_profit`、`market_value` 分别保留开仓价、开仓成本、浮动盈亏、市值原值。`profit_rate` 不乘以 100，也不换算单位。

外层示意：`{"600000.SH": {上述持仓字段}}`。

### 5.4 委托

`GET /api/portfolio/order`，查询 `order`，返回对象数组，空结果为 `[]`。

| 字段 | JSON 类型 | QMT 来源 / 转换 |
| --- | --- | --- |
| `stock_code` | string | `m_strInstrumentID + "." + m_strExchangeID` |
| `order_sys_id` | string | `m_strOrderSysID` |
| `ref` | integer | `m_nRef` |
| `order_ref` | string | `m_strOrderRef` |
| `direction` | integer | `m_nDirection` |
| `offset_flag` | integer | `m_nOffsetFlag` |
| `limit_price` | number | `m_dLimitPrice` |
| `volume_total_original` | integer | `m_nVolumeTotalOriginal` |
| `volume_traded` | integer | `m_nVolumeTraded` |
| `volume_total` | integer | `m_nVolumeTotal` |
| `traded_price` | number | `m_dTradedPrice` |
| `trade_amount` | number | `m_dTradeAmount` |
| `insert_date` | string | `m_strInsertDate` |
| `insert_time` | string | `m_strInsertTime` |
| `remark` | string | `m_strRemark` |
| `order_status` | integer | `m_nOrderStatus` |

`order_sys_id` 为柜台系统订单号，撤单时使用。`volume_total_original` 为原始委托数量，`volume_traded` 为已成交数量，`volume_total` 为剩余数量。日期、时间、备注及状态枚举保持原值。

服务端不按状态过滤，不排序或分页，不从备注中派生 `local_order_id`、`side`、`created_at` 等字段。

### 5.5 成交

`GET /api/portfolio/deal`，查询 `deal`，返回对象数组，空结果为 `[]`。

| 字段 | JSON 类型 | QMT 来源 / 转换 |
| --- | --- | --- |
| `stock_code` | string | `m_strInstrumentID + "." + m_strExchangeID` |
| `order_sys_id` | string | `m_strOrderSysID` |
| `ref` | integer | `m_nRef` |
| `order_ref` | string | `m_strOrderRef` |
| `direction` | integer | `m_nDirection` |
| `offset_flag` | integer | `m_nOffsetFlag` |
| `price` | number | `m_dPrice` |
| `volume` | integer | `m_nVolume` |
| `trade_amount` | number | `m_dTradeAmount` |
| `trade_date` | string | `m_strTradeDate` |
| `trade_time` | string | `m_strTradeTime` |
| `remark` | string | `m_strRemark` |
| `close_profit` | number | `m_dCloseProfit` |

`price`、`volume`、`trade_amount` 分别为成交价格、数量、金额；`close_profit` 为平仓盈亏。记录逐条输出，不按订单合并、不去重、不分页，也不接受日期过滤。`order_sys_id` 是订单号，不应假定其唯一标识一条成交记录。

### 5.6 原始记录

`GET /api/portfolio/org/{handler_type}`，支持 `account`、`order`、`deal`、`position`。

调用 `get_trade_detail_data(account_id, 'stock', handler_type)`，遍历每条记录的公开、非 callable 属性，响应为 `{"data":[记录对象]}`，空结果为：

```json
{"data":[]}
```

保留 `m_strInstrumentID` 等原始属性名，不使用前述格式化函数，不保证固定字段集合，也没有 `default=str` 序列化兜底。

## 6. 实时行情

`POST /api/data/full_tick`

| 字段 | 类型 | 必填 | 默认 | 说明 |
| --- | --- | --- | --- | --- |
| `stocks` | array of string | 否 | `[]` | 原样传给 `ContextInfo.get_full_tick(stocks)` |

```json
{"stocks":["600000.SH","000001.SZ"]}
```

响应直接使用 QMT 行情结果，通常为证券代码到行情对象的映射；内部字段不改名、不裁剪。无法直接序列化的值转为字符串。允许空数组，但具体查询范围由 QMT 决定。底层返回空值时返回 HTTP 500。

## 7. 提交委托

`POST /api/trade/passorder`

| 字段 | 类型 | 必填 | 默认 | 服务端处理 |
| --- | --- | --- | --- | --- |
| `opType` | integer | 是 | — | `int()` |
| `orderType` | integer | 否 | `1101` | `int()` |
| `stockCode` | string | 是 | — | 直接传入 |
| `prType` | integer | 否 | `11` | `int()` |
| `price` | number | 是 | — | `float()` |
| `volume` | integer | 是 | — | `int()` |
| `quickTrade` | integer | 否 | `2` | `int()` |
| `strategyName` | string | 否 | `""` | `str(...).strip()` |
| `orderId` | string | 否 | `""` | `str(...).strip()`，本地订单标识 |

底层参数顺序：

```python
passorder(opType, orderType, account_id, stockCode, prType, price,
          volume, strategyName, quickTrade, orderId, ContextInfo)
```

请求结构示例（实际提交会调用交易函数）：

```json
{
  "opType":23,
  "orderType":1101,
  "stockCode":"600000.SH",
  "prType":11,
  "price":10.0,
  "volume":100,
  "quickTrade":2,
  "strategyName":"trend",
  "orderId":"trend-BUY-example"
}
```

响应示例：

```json
{
  "status":"success",
  "opType":23,
  "stockCode":"600000.SH",
  "strategy_name":"trend",
  "local_order_id":"trend-BUY-example",
  "order_ref":"None"
}
```

`order_ref` 为 `str(passorder返回值)`；示例对应底层返回 `None`，不保证提供柜台系统订单号。它与查询接口中来源于 `m_strOrderRef` 的同名字段来源不同。

`success` 仅表示底层调用未抛异常，不代表已经成交或最终报单成功。服务端未按 `orderId` 做幂等去重，请求超时不能证明未提交。

缺字段、JSON 解析失败及捕获到的类型 / 数值转换错误返回 HTTP 400；底层普通异常返回 502，底层 `HTTPError` 原样传播。封装未检查价格、数量正负、代码非空或枚举有效性。表中为 REST 服务默认值，SDK 显式传参可能不同。

## 8. 撤单

`POST /api/trade/cancel_by_id`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `order_id` | string | 是 | 柜台系统订单号，即查询的 `order_sys_id`，不是本地 `orderId` |

```json
{"order_id":"示例柜台订单号"}
```

先调用 `can_cancel_order(order_id, account_id, 'stock')`，可撤时调用 `cancel(order_id, account_id, 'stock', ContextInfo)`。

成功响应：

```json
{"status":"success","order_id":"示例柜台订单号"}
```

不可撤时响应仍为 HTTP 200：

```json
{
  "status":"failed",
  "order_id":"示例柜台订单号",
  "message":"Order does not exist or cannot currently be canceled"
}
```

若 `cancel()` 返回值严格为 `False`，返回 `{"status":"failed","order_id":"示例柜台订单号"}`，无 `message`，仍为 HTTP 200；其他返回值均标记 `success`。最终结果应再查询委托确认。缺失或空字符串订单号返回 400，QMT 普通调用异常返回 500。

## 9. 发行数据

`POST /api/trade/ipo_data`

| 字段 | 类型 | 必填 | 默认 | 说明 |
| --- | --- | --- | --- | --- |
| `type` | string | 否 | `"STOCK"` | 原样传给全局 `get_ipo_data(type)`，不转换大小写或校验枚举 |

```json
{"type":"STOCK"}
```

响应直接序列化底层结果，不包装或重命名字段，具体结构由 QMT 提供。使用默认参数也需发送 `{}`。

## 10. Python 版本

`GET /api/sys/python_version`，无参数。

```json
{
  "python_version":"<sys.version>",
  "python_version_info":{
    "major":3,
    "minor":11,
    "micro":0,
    "releaselevel":"final",
    "serial":0
  }
}
```

值仅为示例，实际取自服务进程的 `sys.version` 和 `sys.version_info`。

## 11. 错误响应

匹配到 `BaseHandler` 的接口默认声明 `Content-Type: application/json; charset=utf-8`，但 `write_error()` 实际输出 `self._reason` 原始文本，**不是 JSON 错误对象**。客户端应先检查 HTTP 状态，错误正文按文本处理。

| 场景 | HTTP 状态 | 行为 |
| --- | --- | --- |
| Token 缺失或不匹配 | 500 | 未显式设置 reason，正文通常为 `Internal Server Error` |
| 单证券查询缺代码 / 无资产 / 无行情 | 500 | 通常为默认错误原因文本 |
| `safe_call()` 中普通异常 | 500 | `QMT: <函数名> call failed.` |
| 下单参数解析 / 转换异常 | 400 | `Invalid order parameters: ...` |
| 下单底层普通异常 | 502 | `QMT order submission failed` |
| 撤单订单号缺失或为空 | 400 | 通常为 `Bad Request` |
| 不可撤或底层明确返回 False | 200 | JSON 中 `status=failed` |
| 路由不存在 | 404 | Tornado 默认错误处理，不保证上述格式 |
| 方法不支持 | 405 | 已匹配 Handler 的错误处理 |

除下单外，POST 未统一捕获 JSON 解析错误，非法 JSON 可能返回 500；非对象 JSON 也未统一校验。`safe_call()` 遇到底层 `HTTPError` 原样传播。

## 12. 只读调用示例

PowerShell 示例，不提交交易：

```powershell
$apiBase = 'http://127.0.0.1:10086'
$apiHeaders = @{ 'X-Token' = '<服务端 TOKEN>' }
Invoke-RestMethod -Uri "$apiBase/api/portfolio" -Headers $apiHeaders
Invoke-RestMethod -Uri "$apiBase/api/get/stock_name?stock_code=600000.SH" -Headers $apiHeaders
Invoke-RestMethod -Method Post -Uri "$apiBase/api/data/full_tick" -Headers $apiHeaders -ContentType 'application/json' -Body '{"stocks":["600000.SH"]}'
```