kyugao/qmt_bridge

Fork 0

Files

T

Docker 22a5b8ca04 chore: init qmt_bridge repo (HTTP+WS bridge, MCP endpoint, docs, references)

2026-08-26 16:53:15 +08:00

22 KiB

Raw Blame History

RPC API 参考

本文档列出大 QMT RPC 服务对外暴露的全部方法、参数、返回值，以及每个方法在大 QMT 内部的实现来源与注意事项。

方法集合的权威定义在 src/bigqmt_signal_trader/redis_rpc.py： READ_METHODS（只读白名单）、ORDER_METHODS（下单白名单）、MARKET_DATA_METHODS（转发给行情适配器）、METHOD_ALIASES（MiniQMT 风格别名）。

总览

类别	方法数	说明
系统	1	`ping`
行情快照	2	`get_ticks` / `get_instrument`
行情/K线/基本面（转发适配器）	84	见下表
账户/持仓/委托	5	`get_asset` / `get_positions` / `query_stock_position` / `query_orders` / `query_trades`
交易扩展查询（官方函数）	13	`get_value_by_order_id` / `get_last_order_id` / `get_ipo_data` / `get_new_purchase_limit` / `get_history_trade_detail_data` / 融资融券5个 / 期权持仓2个 / 港股通汇率
持仓同步	1	`sync_positions`
下单/撤单	2	`submit_order` / `cancel_order`（默认关闭）
合计	117 只读 + 2 下单 = 119

另有 12 个 MiniQMT 风格别名（见末节），调用时自动映射到上表方法。

1. 系统

`ping`

参数：无
返回：{"pong": True, "account_id": "...", "server_time": "YYYY-MM-DD HH:MM:SS"}
用途：探活、确认 RPC 服务在线与归属账号。
实测延迟：Redis ~13ms（p50）。

2. 行情快照

`get_ticks`

别名：get_full_tick
参数：
- codes（list[str]，必填）：股票代码列表，如 ["000001.SZ", "600000.SH"]
- 或 code（str）：单个代码（codes 优先）
- 支持整市场快照：codes=["SH"] / ["SZ"] / ["BJ"] / ["HK"]

返回：dict，key 为股票代码，value 含五档盘口：

{"000001.SZ": {
    "lastPrice": 12.34, "open": 12.20, "high": 12.50, "low": 12.10,
    "lastClose": 12.25, "volume": 12345600, "amount": 1.5e8,
    "askPrice": [12.33, ...10档], "bidPrice": [12.32, ...10档],
    "askVol":  [...], "bidVol": [...],
    "pvolume": ..., "transactionNum": ..., "stockStatus": ...,
    "time": 1719...（毫秒时间戳）, "stime": "20240701 15:00:00"
}}

实现：透传 ContextInfo.get_full_tick(code_list)，原生返回什么字段就回传什么字段（不做转换）。
注意：整市场快照（["SH"]）数据量大，建议配合客户端 full_tick_cache 降载。

`get_instrument`

别名：get_instrument_detail / get_instrumentdetail
参数：code（str，必填）：股票代码
返回：dict，合约详情（名称、上市日、合约乘数、最小变动价位等约 30 个字段）。
实现：ContextInfo.get_instrumentdetail(code)。

2.5 全推行情订阅（server 推送，对齐 miniqmt `subscribe_whole_quote`）

这三个方法只管理订阅生命周期与心跳；行情数据本身走独立的 server→client 推送通道（zmq PUB/SUB 或 redis pub/sub，msgpack 编码、json 兜底），不经过 RPC 响应。多 client 订阅同一组合（frozenset 规范化）共享同一个大 QMT ContextInfo.subscribe_whole_quote，引用计数归零（全部退订或全部心跳超时）才真正退订大 QMT。详见 docs/SUBSCRIBE_WHOLE_QUOTE_PUSH.md。

`subscribe_whole_quote`

参数：client_id（str，必填，client 进程级稳定 id）、sub_id（str，必填，client 侧订阅号）、codes（list[str]，必填）：市场代码（["SH","SZ"]）或品种代码列表。
返回：{"combo_key": str, "topic": str, "push_endpoint": str}。topic 即推送通道的过滤主题；push_endpoint 为 zmq PUB 地址（redis 推送时为空，client 本地推导 channel 名）。
语义：首个 client 订阅该组合时建立大 QMT 订阅；同组合后续 client 共享。幂等（重复 subscribe 不重复建订阅，用于 server 重启后 client 重放恢复）。

`unsubscribe_whole_quote`

参数：client_id、sub_id（均 str，必填）。
返回：{}。
语义：移除该 (client_id, sub_id) 的引用；该组合最后一个 client 离开时退订大 QMT。未知 sub_id 为 no-op。

`quote_keepalive`

参数：client_id、sub_id（均 str，必填）。
返回：{}。
语义：刷新该订阅的 last_seen。client 每 heartbeat_interval（默认 3s）发送一次；server 端某 client 超过 heartbeat_timeout_seconds（默认 30s = 10 个心跳周期）无心跳则被 reaper 移除，组合清空后退订大 QMT。

3. 行情 / K线 / 板块 / 日历 / 下载 / 财务 / 期权 / 龙虎榜 / 资金流 / 因子

下列 84 个方法统一通过 _handle_market_data_method 按方法名转发给 BigQmtMarketDataProvider 的同名方法，参数字典直接 **kwargs 展开。调用方按下方签名传参即可。客户端兼容层对常用方法有显式封装，其余用 xtdata.call_method(name, **params)。

3.1 品种/类型

方法	参数	说明
`get_instrument_type`	`code`（str），可选 `variety_list`（list）	返回 `{"stock":bool,"fund":bool,"etf":bool,"bond":bool,"index":bool}`；传 `variety_list` 则只返回指定品种的 bool

3.2 K线/历史行情

方法	参数	返回
`get_market_data`	`field_list`(list) `stock_list`(list) `period`("1d"/"1m"/"5m"/"tick") `start_time` `end_time` `count`(int) `dividend_type`("none"/"front"/"back") `fill_data`(bool)	DataFrame（自动还原）
`get_market_data_ex`	同上	`dict[code -> DataFrame]`
`get_local_data`	同上 + 可选 `data_dir`	`dict[code -> DataFrame]`

DataFrame / Series 在 RPC 协议层用 __bigqmt_type__ 标记序列化，客户端 xtquant_compat 自动还原为 pandas 对象。

3.3 板块

方法	参数	返回	Big QMT 实现说明
`get_stock_list_in_sector`	`sector_name`(str) 可选 `real_timetag`(int,默认-1)	`list[str]` 代码列表	`ContextInfo.get_stock_list_in_sector`
`get_sector_list`	无	`list[str]` 板块名	⚠️ 见下方说明
`get_sector_info`	`sector_name`(str)	板块详情	`ContextInfo.get_sector_info`

get_sector_list 在大 QMT 的实现说明（重要）：板块列表是全局数据，原生 xtdata SDK 的 get_sector_list()（SDK 第 784 行）才有，ContextInfo 没有此方法。但大 QMT（完整交易端）进程里，原生 xtdata SDK 的 get_client() 连不上行情服务（报「无法连接行情服务」，因为没有 MiniQMT 进程写 ~/.xtquant/*/xtdata.cfg）。

因此适配器按优先级降级：

原生 xtdata SDK（MiniQMT 环境）→ 真实板块列表
ContextInfo.get_sector_list（不存在，跳过）
fallback：返回一组常用板块名（沪深A股/沪市A股/深市A股/科创板/创业板/沪深ETF/上证期权/深证期权/中金所 等 13 个），可继续驱动 get_stock_list_in_sector(name)。

3.4 交易日历 / 节假日

方法	参数	返回	Big QMT 实现
`get_trading_dates`	`market`(str 如 "SH") `start_time` `end_time` `count`(int)	`list` 日期（`YYYYMMDD` 字符串或毫秒时间戳）	`ContextInfo.get_trading_dates` ✅
`get_holidays`	无	`list[str]` 假日（`YYYYMMDD`）	⚠️ fallback 见下
`get_markets`	无	`list[str]` = `["SH","SZ","BJ","HK"]`	合成（Big QMT/xtdata 均无此函数）
`get_market_last_trade_date`	`market`(str)	最后一交易日（`YYYYMMDD`）	由 `get_trading_dates(market,count=1)` 派生

get_trading_dates 参数说明（重要）： ContextInfo 桩签名是 get_trading_dates(stockcode, ...)，xtdata SDK 签名是 get_trading_dates(market, ...)——第一参数语义不同。本系统所有调用方传的都是 market（如 "SH"），走 ContextInfo 时 QMT 内部会从 stockcode 推 market，A 股日历各市场基本一致，故结果正确。

get_holidays 在大 QMT 的实现说明（重要）：节假日列表同样是全局数据，只有原生 xtdata SDK 的 get_holidays()（SDK 第 1197 行）有。大 QMT 进程连不上 SDK 行情服务时，适配器从交易日历反推：取 [去年1月1日, 今天] 区间内所有工作日（周一至周五），凡是 get_trading_dates("SH") 里没有的就是假日。比 SDK 慢但结果正确。

3.5 数据下载

方法	参数	说明
`download_history_data`	`stock_code` `period` `start_time` `end_time` 可选 `incrementally`	下载单合约历史
`download_history_data2`	`stock_list`(list) `period` `start_time` `end_time` 可选 `incrementally`	批量下载
`download_holiday_data`	`incrementally`(bool)	下载假日数据
`download_etf_info`	无	下载 ETF 信息

3.6 财务 / ETF / 期权 / IPO

方法	参数	说明
`get_financial_data`	`stock_list`(list) `table_list`(list) `start_time` `end_time` `report_type`("report_time")	财务数据
`download_financial_data`	同上 + `incrementally`	下载财务
`download_financial_data2`	`stock_list` `table_list` `start_time` `end_time`	批量下载财务
`get_etf_info`	无	ETF 信息
`get_ipo_info`	`start_time` `end_time`	IPO 信息
`get_option_list`	`undl_code` `dedate` `opttype` `isavailavle`(bool)	期权列表
`get_his_option_list`	`undl_code` `dedate`	历史期权
`get_his_option_list_batch`	`undl_code` `start_time` `end_time`	批量历史期权
`get_divid_factors`	`stock_code` 可选 `start_time`/`end_time`	除权除息因子

get_divid_factors 参数说明（重要）： ContextInfo 桩签名是 get_divid_factors(marketAndStock, date='')——只收 2 个参数（代码 + 单个日期）。适配器接受 start_time/end_time 以保持接口兼容，但实际只把 end_time（或 start_time）作为单个 date 传入。

3.7 因子 / 模型

方法	参数	说明
`call_formula`	`formula_name` `stock_code` `period` `start_time` `end_time` `count` `dividend_type` `extend_param`(dict)	调用公式
`subscribe_formula`	同上	订阅公式
`unsubscribe_formula`	`request_id`	取消订阅
`get_formula_result`	`request_id` `start_time` `end_time` `count` `timeout_second`	取公式结果
`gen_factor_index`	`data_name` `formula_name` `vars` `sector_list`(list) `start_time` `end_time` `period` `dividend_type`	生成因子

3.8 龙虎榜 / 股东 / 换手率 / 行业

方法	参数	说明
`get_longhubang`	`stock_list`(list) `start_time` `end_time` `count`(int)	龙虎榜明细（DataFrame）
`get_top10_share_holder`	`stock_list`(list) `data_name`("holder"/"flow_holder") `start_time` `end_time` `report_type`("report_time"/"announce_time")	十大股东
`get_holder_num`	`stock_list`(list) `start_time` `end_time` `report_type`	股东户数
`get_turnover_rate`	`stock_code`(list) `start_time` `end_time`（均 8 位 YYYYMMDD）	区间换手率（DataFrame）
`get_industry`	`industry_name`(str)	行业成分股
`get_his_st_data`	`stock_code`(str)	历史 ST 状态

3.9 期权定价 / 隐含波动率

方法	参数	说明
`bsm_price`	`opt_type`("C"/"P") `target_price`(数值或 list) `strike_price` `risk_free` `sigma` `days` `dividend`(默认0)	B-S-M 期权定价（可批量）
`bsm_iv`	`opt_type` `target_price` `strike_price` `option_price` `risk_free` `days` `dividend`	隐含波动率反推
`get_option_iv`	`opt_code`(str)	单只期权隐含波动率
`get_option_detail_data`	`stockcode`(str)	期权合约详情
`get_option_undl_data`	`undl_code_ref`(str，空=全市场)	标的下所有期权
`get_option_undl`	`opt_code`(str)	期权的标的代码

3.10 财务扩展 / 因子库

方法	参数	说明
`get_raw_financial_data`	`field_list`(list) `stock_list`(list) `start_time` `end_time` `report_type` `data_type`("dict"/"frame")	原始财务（未字段对齐）
`get_factor_data`	`field_list`(list) `stock_list`(list) `start_date` `end_date`	因子库数据
`get_his_index_data`	`stock_code`(str)	历史指数权重

3.11 期货 / 合约 / 资金流

方法	参数	说明
`get_main_contract`	`code_market`(str)	主力合约
`get_his_contract_list`	`market`(str)	历史合约列表
`get_date_location`	`date`	日期在交易日历的位置
`get_ETF_list`	`market` `stock_code` `type_list`(list)	ETF 列表
`get_north_finance_change`	`period`	北向资金流入流出
`get_hkt_statistics`	`stock_code`	港股通统计
`get_hkt_details`	`stock_code`	港股通明细

3.12 板块管理 / 基础查询

方法	参数	说明
`create_sector`	`sector_name` `stock_list`(list)	创建/更新自定义板块（写操作）
`get_stock_name`	`stock`	股票名称（如「平安银行」）
`get_stock_type`	`stock`	股票类型
`get_last_close`	`stock`	昨收价
`get_last_volume`	`stock`	昨量
`get_open_date`	`stock`	上市日期
`get_contract_expire_date`	`stock`	到期日（股票返回 99999999）
`get_contract_multiplier`	`stockcode`	合约乘数
`get_float_caps`	`stockcode`	流通市值
`get_total_share`	`stockcode`	总股本
`get_turn_over_rate`	`stockcode`	换手率（单值版）
`get_weight_in_index`	`mtkindexcode` `stockcode`	指数中权重
`get_svol`	`stock`
`get_bvol`	`stock`
`get_risk_free_rate`	`index`(int, 默认-1)	无风险利率
`get_close_price`	`market` `stock_code` `real_timetag` `period`(默认86400000) `divid_type`(默认0)	指定时点收盘价

4. 账户 / 持仓 / 委托

下列方法的 account_id 参数均可选（不传则用服务端配置的账号）。也接受 account（对象/dict）。

`get_asset`

别名：query_stock_asset
参数：account_id(str, 可选)
返回：{"cash":..., "total_asset":..., "market_value":..., "account_id":...}
实现：get_trade_detail_data(account, type, "ASSET")。

`get_positions`

别名：query_stock_positions
参数：account_id(str, 可选)
返回：dict[code -> {stock_code, stock_name, volume, available, cost, ...}]
实现：get_trade_detail_data(account, type, "POSITION")。
容错：QMT 上下文未绑定时报错，适配器降级为返回 {}。

`query_stock_position`

参数：account_id(可选) stock_code(str, 必填) 或 code
返回：单个持仓 dict（同上 value 结构），无持仓返回 None。

`query_orders`

参数：account_id(可选) strategy_name(str, 默认 "" 返回全部) cancelable_only(bool)
返回：list[OrderSnapshot]，每项含 order_sys_id/user_order_id/stock_code/action/volume/traded_volume/status/price 等。
实现：get_trade_detail_data(account, type, "ORDER", strategy)。
strategy_name 陷阱（重要）：get_trade_detail_data 按 strategy_name 过滤委托——下单时用的 strategy_name 必须和查询时一致。默认传 "" 返回全部委托（不按 strategy_name 过滤）。如需过滤，显式传 strategy_name。
容错：QMT 上下文未绑定时报错，降级为 []。

`query_trades`

参数：account_id(可选) strategy_name(str, 默认 "" 返回全部)
返回：成交明细 list。
strategy_name 陷阱：同 query_orders，默认 "" 返回全部成交。

4.5 官方交易查询函数（Big QMT 运行时注入）

这些函数和 passorder 一样由 Big QMT 进程在运行时注入全局命名空间，不在 ContextInfo 桩里。函数名严格按官方文档（trading_function.html）。无对应权限（如两融账户）时降级为空列表。

方法	参数	说明
`get_value_by_order_id`	`order_id`（必填）	按 order_id 查委托详情
`get_last_order_id`	`account_id`(可选)	最近委托号
`get_ipo_data`	`account_id`(可选)	新股数据
`get_new_purchase_limit`	`account_id`(可选)	新股申购额度
`get_history_trade_detail_data`	`account_id`(可选) `detail_type`("DEAL"/"ORDER") `start_date` `end_date`	历史成交明细
`get_assure_contract`	`account_id`(可选)	融资标的（担保品）合约
`get_enable_short_contract`	`account_id`(可选)	融券标的合约
`get_unclosed_compacts`	`account_id`(可选)	未平仓合约（负债）
`get_closed_compacts`	`account_id`(可选)	已平仓合约
`get_debt_contract`	`account_id`(可选)	负债合约
`get_option_subject_position`	`account_id`(可选)	期权标的持仓
`get_comb_option`	`account_id`(可选)	组合期权
`get_hkt_exchange_rate`	无	港股通汇率

融资融券查询的正确方式：官方文档明确 get_trade_detail_data 的合法 strDatatype 只有 6 个（ACCOUNT/POSITION/POSITION_STATISTICS/ORDER/DEAL/TASK）。两融查询必须用上述独立函数，不要传 "CREDIT" 等字符串。

5. 持仓同步

`sync_positions`

参数：account_id(可选) reason(str, 默认 "rpc")
返回：AccountSnapshot（含 asset + positions）
用途：主动触发把当前持仓快照写入 Redis（key bigqmt:positions:{account_id}），供客户端缓存。
注意：属 LISTENER_DEFERRED_METHODS，在 redis 传输 + listener 模式下会延迟到 adjust 线程执行（避免阻塞收包线程）。

6. 下单 / 撤单（默认关闭）

⚠️ 默认 rpc_allow_order_methods=False，调用会被 PermissionError 拒绝。确认账号/风控/接入方后，在配置里设 "rpc_allow_order_methods": True 开启。

`submit_order`

别名：order_stock / order_stock_async
参数：
- stock_code(str, 必填)
- action(str)："BUY" / "SELL"；或 order_type（23/STOCK_BUY/BUY 买，24/STOCK_SELL/SELL 卖）
- volume(int, 必填) 或 order_volume
- price(float)
- price_type(str, 默认 "LIMIT")：LIMIT(11)/LATEST(5)/对手价(44) 等
- account_id(可选) strategy_name signal_id remark/order_remark
返回：{"order_sys_id":..., "user_order_id":...}
实现：passorder(op_type, combo_type, account, code, price_type, price, volume, ..., quicktrade=2)。

`cancel_order`

别名：cancel_order_stock / cancel_order_stock_sysid
参数：order_sys_id 或 order_sysid 或 order_id（必填）可选 user_order_id market
返回：撤单结果。

7. MiniQMT 风格别名

旧代码若用 MiniQMT 方法名，调用时自动映射（无需改业务代码）：

别名（MiniQMT）	映射到
`get_full_tick`	`get_ticks`
`get_instrument_detail` / `get_instrumentdetail`	`get_instrument`
`getDividFactors`	`get_divid_factors`
`query_stock_asset`	`get_asset`
`query_stock_positions`	`get_positions`
`query_stock_orders`	`query_orders`
`query_stock_trades`	`query_trades`
`order_stock` / `order_stock_async`	`submit_order`
`cancel_order_stock` / `cancel_order_stock_sysid`	`cancel_order`

客户端用 xtquant_compat 时，xt_trader.query_stock_positions(acc)、xtdata.get_full_tick([...]) 等调用会自动走别名映射，最终命中上表方法。

8. 大 QMT 环境的能力边界（重要）

核对 QMT 官方文档（trading_function.html / data_function.html）、ContextInfo IDE 桩（_PyContextInfo.py）、原生 xtdata SDK（bin.x64/.../xtquant/xtdata.py）三处后，确认：

能力	大 QMT（完整交易端）	MiniQMT / xtdata SDK
行情快照（`get_full_tick`）	✅ ContextInfo	✅ xtdata
K线（`get_market_data_ex` 等）	✅ ContextInfo	✅ xtdata
合约详情（`get_instrumentdetail`）	✅ ContextInfo	✅ xtdata
板块内股票（`get_stock_list_in_sector`）	✅ ContextInfo	✅ xtdata
交易日历（`get_trading_dates`）	✅ ContextInfo	✅ xtdata
龙虎榜/股东/换手率（`get_longhubang` 等）	✅ ContextInfo	❌ xtdata 无
期权定价（`bsm_price`/`bsm_iv`/`get_option_iv`）	✅ ContextInfo	❌ xtdata 无
北向资金/港股通（`get_north_finance_change` 等）	✅ ContextInfo	❌ xtdata 无
基础查询（`get_stock_name`/`get_float_caps` 等）	✅ ContextInfo	❌ xtdata 无
板块列表（`get_sector_list`）	⚠️ fallback 常用板块	✅ xtdata（需连行情服务）
节假日（`get_holidays`）	⚠️ 从日历反推	✅ xtdata（需连行情服务）
`get_markets`	合成 4 市场	无此函数
`get_market_last_trade_date`	从日历派生	无此函数
交易（下单/撤单/查持仓）	✅ passorder + get_trade_detail_data	✅ XtQuantTrader

结论：除「板块完整列表」「节假日原始数据」在大 QMT 端只能 fallback 外，其余 API 在大 QMT 环境下均能返回真实数据。需要原始板块/假日数据时，需额外跑一个 MiniQMT 进程（让 xtdata.get_client() 能连上）。

9. 错误约定

RPC 响应统一为 {"ok": bool, "data": ..., "error": "..."}：

ok=True：data 为方法返回值（DataFrame/Series 已序列化，客户端自动还原）。
ok=False：error 为错误信息。常见：
- rpc method is not allowed: X —— 方法不在白名单（rpc_listener_methods 配置）。
- order rpc methods are disabled —— 下单未开启。
- ContextInfo.X is not available —— 该 ContextInfo 方法在当前 QMT 版本不存在。
- 无法连接行情服务 —— 原生 xtdata SDK 连不上（仅 sector_list/holidays 的 SDK 路径）。

22 KiB Raw Blame History Unescape Escape