kyugao/qmt_bridge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
22a5b8ca048f5c4e288f0a656353fe8d90440868
qmt_bridge/reference/xtquant_big_convert/qmt-trader/references/api_reference.md
T

16 KiB
Raw Blame History

QMT API 参考手册

本文档是 qmt-trader skill 的完整 API 参考。当 SKILL.md 的速查不够用时，查阅本文件获取 参数细节、返回值结构和已知陷阱。

1. 初始化与配置

配置来源（优先级从高到低）

  1. 环境变量

    变量 默认 说明
    BIGQMT_ACCOUNT_ID — 资金账号
    BIGQMT_REDIS_HOST 127.0.0.1 Redis 地址
    BIGQMT_REDIS_PORT 6379 Redis 端口
    BIGQMT_REDIS_DB 5 Redis DB
    BIGQMT_REDIS_PASSWORD — Redis 密码
    BIGQMT_RPC_TRANSPORT redis 传输方式 redis/zmq
    BIGQMT_RPC_TIMEOUT_SECONDS 6.0 RPC 超时

  2. 配置文件 bigqmt_signal_trader_client_config.py（在 PYTHONPATH 中，gitignored）

  3. 备选配置文件 bigqmt_signal_trader_local_config.py

Python 初始化

from bigqmt_signal_trader.xtquant_compat import StockAccount, configure, xt_trader, xtdata

configure()  # 从配置/环境变量初始化
acc = StockAccount(xt_trader.client.account_id, "STOCK")

2. 行情数据 API

2.1 get_full_tick — 实时五档盘口

xtdata.get_full_tick(code_list)
  • 参数: code_list: list[str]，如 ["000001.SZ", "600000.SH"]；也支持整市场 ["SH"], ["SZ"]
  • 返回: dict[code -> dict]，每只含 lastPrice/open/high/low/lastClose/volume/amount/ bidPrice(10档)/askPrice(10档)/bidVol/askVol/time/stime
  • CLI: python qmt.py tick 600000.SH 000001.SZ
  • 注意: 整市场快照数据量大（5000+ 股），超时自动设 30 秒

2.2 get_market_data_ex — K线/历史行情

xtdata.get_market_data_ex(
    field_list=None,      # ["close","open","high","low","volume","amount"] 或 None=全部
    stock_list=None,      # ["000001.SZ"]
    period="1d",          # "1d"/"1m"/"5m"/"15m"/"30m"/"60m"/"tick"
    start_time="",        # "YYYYMMDD" 或 "YYYYMMDDHHMMSS"
    end_time="",
    count=-1,             # -1=不限
    dividend_type="none", # "none"/"front"(前复权)/"back"(后复权)
    fill_data=True,       # 是否填充缺失
)
  • 返回: dict[code -> pandas.DataFrame]，index 是时间戳字符串，列含 time(epoch ms)/open/high/low/close/volume/amount
  • CLI: python qmt.py kline 600000.SH --period 1d --count 60 --dividend front
  • 自愈: 请求复权但服务端缺原始数据时（返回全 0），自动触发下载+重试
  • 陷阱: 前/后复权必须先在服务端下载原始数据，否则返回全 0（已自愈但仍可能首次慢）

2.3 get_instrument_detail — 合约详情

xtdata.get_instrument_detail(stock_code)  # 别名 get_instrumentdetail
  • 返回: dict，含名称/上市日/合约乘数/最小变动价位等约 30 字段
  • CLI: python qmt.py instrument 600000.SH

2.4 get_stock_list_in_sector — 板块成分股

xtdata.get_stock_list_in_sector(sector_name)  # 如 "沪深A股", "科创板", "创业板"
  • 返回: list[str] 代码列表
  • CLI: python qmt.py sector "沪深A股"

2.5 get_sector_list — 板块列表

xtdata.get_sector_list()
  • 返回: list[str]
  • CLI: python qmt.py sector
  • 注意: 大 QMT 环境 fallback 返回 13 个常用板块名（非完整列表）

2.6 get_trading_dates — 交易日历

xtdata.get_trading_dates(market="SH", start_time="", end_time="", count=-1)
  • CLI: python qmt.py trading-dates --count 10

2.7 get_north_finance_change — 北向资金

xtdata.get_north_finance_change(period="1d")
  • CLI: python qmt.py north

2.8 get_longhubang — 龙虎榜

xtdata.get_longhubang(stock_list=["600000.SH"], start_time="", end_time="", count=5)
  • 返回: pandas.DataFrame
  • CLI: python qmt.py longhubang 600000.SH --count 5

2.9 get_financial_data — 财务数据

xtdata.get_financial_data(
    stock_list=["000001.SZ"],
    table_list=["Capital.CAPITAL"],  # 表名
    start_time="", end_time="",
)
  • CLI: python qmt.py financial 000001.SZ --tables Capital.CAPITAL

2.10 download_history_data2 — 下载历史数据

xtdata.download_history_data2(
    stock_list=["600654.SH"], period="1d",
    start_time="20240101", dividend_type="front",
)
  • 返回: {"finished": N, "total": M}
  • CLI: python qmt.py download 600654.SH --period 1d --start 20240101 --dividend front

2.11 subscribe_whole_quote — 全推行情订阅

sub_id = xtdata.subscribe_whole_quote(["SH","SZ"], callback=on_quote)
# ... 运行策略 ...
xtdata.unsubscribe_quote(sub_id)
  • 机制: 服务端真推送（非轮询），增量推送有变化的品种
  • CLI: python qmt.py quote-subscribe SH SZ --max 10 --timeout 30
  • 心跳: 客户端 3 秒一次 keepalive，服务端重启后自动恢复

3. 账户/持仓/委托查询 API

3.1 query_stock_asset — 查询资产

asset = xt_trader.query_stock_asset(acc)
  • 返回属性: account_id / cash(可用现金) / frozen_cash / total_asset / market_value
  • CLI: python qmt.py account
  • 容错: RPC 失败时从 Redis 缓存 bigqmt:positions:{account_id} 读取

3.2 query_stock_positions — 查询全部持仓

positions = xt_trader.query_stock_positions(acc)
  • 返回属性: stock_code / stock_name / volume(总持仓) / can_use_volume(可用) / avg_price(成本) / price(最新价) / market_value / frozen_volume / yesterday_volume
  • CLI: python qmt.py positions [code]

3.3 query_stock_position — 查询单只持仓

pos = xt_trader.query_stock_position(acc, "600000.SH")
  • 返回: 单个对象或 None

3.4 query_stock_orders — 查询委托

orders = xt_trader.query_stock_orders(acc, cancelable_only=False, strategy_name="")
  • 返回属性: stock_code / order_type(23=BUY,24=SELL) / order_status / order_volume / traded_volume / price / order_sysid / order_remark
  • CLI: python qmt.py orders [--cancelable] [--strategy ""]
  • ⚠️ strategy_name 陷阱: 下单时的 strategy_name 必须和查询时一致。服务端默认 "" 返回全部； 客户端 BigQmtXtTrader 默认 "bigqmt_signal_trader"。用 "" 查全部最安全。

3.5 query_stock_trades — 查询成交

trades = xt_trader.query_stock_trades(acc, strategy_name="")
  • 返回属性: stock_code / order_type / traded_volume / traded_price / traded_at / order_sysid / trade_id
  • CLI: python qmt.py trades

3.6 委托状态码

值 常量 含义
48 ORDER_UNREPORTED 未申报
49 ORDER_WAIT_REPORTING 等待申报
50 ORDER_REPORTED 已申报
51 ORDER_REPORTED_CANCEL 已申报撤单
52 ORDER_PARTSUCC_CANCEL 部成撤单
53 ORDER_PART_CANCEL 部撤
54 ORDER_CANCELED 已撤
55 ORDER_PART_SUCC 部分成交
56 ORDER_SUCCEEDED 全部成交
57 ORDER_JUNK 废单
255 ORDER_UNKNOWN 未知

可撤状态: 49, 50, 55

4. 下单 API

4.1 order_stock — 同步下单

from bigqmt_signal_trader.xtquant_compat import STOCK_BUY, STOCK_SELL, FIX_PRICE, LATEST_PRICE

order_id = xt_trader.order_stock(
    acc,            # StockAccount
    stock_code,     # "600000.SH"
    order_type,     # STOCK_BUY(23) / STOCK_SELL(24)
    order_volume,   # int，委托数量
    price_type,     # FIX_PRICE(11) / LATEST_PRICE(5)
    price,          # float，限价单价格（最新价时传 0）
    strategy_name,  # str
    order_remark,   # str，user_order_id
)
  • 返回: order_sys_id(字符串) 或 -1(失败)
  • CLI: python qmt.py buy 600000.SH 100 --price 7.50 [--strategy s] [--remark r]
  • CLI: python qmt.py sell 600000.SH 100 --price 7.50
  • ⚠️ 权限: 服务端默认 rpc_allow_order_methods=False，必须显式开启才能下单
  • ⚠️ 超时: 超时后委托可能已提交，先查 query_orders 确认，避免重复下单

4.2 order_stock_async — 异步下单

seq = xt_trader.order_stock_async(acc, code, order_type, vol, price_type, price, strategy, remark)
  • 返回: seq（结果通过 callback 回调）

4.3 order_stock_batch — 批量下单

results = xt_trader.order_stock_batch(acc, orders, batch_id="")
# orders: list[dict]，每项含 stock_code/action/volume/price/price_type/strategy_name
  • 上限: 500 条/批

4.4 信用交易委托类型

常量 值 用途
CREDIT_BUY 23 担保品买入
CREDIT_SELL 24 担保品卖出
CREDIT_FIN_BUY 27 融资买入
CREDIT_SLO_SELL 28 融券卖出
CREDIT_BUY_SECU_REPAY 29 买券还券
CREDIT_DIRECT_SECU_REPAY 30 直接还券
CREDIT_SELL_SECU_REPAY 31 卖券还款
CREDIT_DIRECT_CASH_REPAY 32 直接还款

5. 撤单 API

5.1 cancel_order_stock_sysid

success = xt_trader.cancel_order_stock_sysid(acc, market, order_sysid)
# market: "SH" / "SZ" / ""
  • CLI: python qmt.py cancel <order_sysid> --market SH

5.2 cancel_order_stock

success = xt_trader.cancel_order_stock(acc, order_id)
# 等价于 cancel_order_stock_sysid(acc, "", order_id)

6. 回调系统

from bigqmt_signal_trader.xtquant_compat import XtQuantTraderCallback

class MyCallback(XtQuantTraderCallback):
    def on_stock_order(self, order): ...       # 委托变更
    def on_stock_trade(self, trade): ...        # 成交推送
    def on_order_error(self, error): ...        # 委托错误
    def on_cancel_error(self, error): ...       # 撤单错误
    def on_order_stock_async_response(self, resp): ...
    def on_account_status(self, status): ...

xt_trader.register_callback(MyCallback())
xt_trader.start()
xt_trader.connect()
xt_trader.subscribe(acc)

事件推送通过 Redis pubsub 频道:

  • bigqmt:exec:order:{account_id}
  • bigqmt:exec:trade:{account_id}
  • bigqmt:exec:order_error:{account_id}
  • bigqmt:exec:cancel_error:{account_id}

7. 关键陷阱速查

7.1 strategy_name 不匹配

  • 下单用 strategy_name="rpc_test" → 查询用 strategy_name="bigqmt_signal_trader" → 返回空
  • 解决: 查询时传 strategy_name="" 返回全部，或保持一致

7.2 下单静默失败

  • passorder 调用成功但委托没进系统（QMT 风控拒绝但没报错）
  • 解决: 服务端下单后等 0.5 秒查 query_orders 确认；检查返回的 server_error 字段

7.3 复权 K 线返回全 0

  • 服务端缺原始数据时，前/后复权返回的 close 全是 0.0
  • 解决: 先 download_history_data2 下载原始数据（客户端有自愈机制）

7.4 Transport 不匹配

  • 客户端 redis / 服务端 zmq → ping 超时
  • 解决: 两端 transport 字段保持一致

7.5 QMT 必须运行在实盘模式

  • 模拟模式下委托进 QMT 界面但不在真实委托队列，query_orders 查不到
  • order_stock 返回 -1，触发 on_order_error

7.6 整市场快照数据量大

  • get_full_tick(["SH"]) 返回 5000+ 股完整盘口
  • 解决: 启用 full_tick_cache 或增大超时（已自动设 30 秒）

7.7 全推行情是增量的

  • subscribe_whole_quote 的大 QMT 回调只推有变化的品种
  • 解决: 订阅成功后客户端自动调一次 get_full_tick 打底

7.8 下单超时与重复下单

  • order_stock 超时 → 委托可能已提交但没收到响应
  • 解决: 超时后先查 query_orders/query_trades 确认状态，再决定是否重试

8. 常量速查

交易常量

常量 值 用途
STOCK_BUY 23 股票买入
STOCK_SELL 24 股票卖出
FIX_PRICE 11 限价/指定价
LATEST_PRICE 5 最新价
MARKET_PEER_PRICE_FIRST 44 对手方最优价

账号类型

常量 值
FUTURE_ACCOUNT 1
SECURITY_ACCOUNT 2
CREDIT_ACCOUNT 3
FUTURE_OPTION_ACCOUNT 5
STOCK_OPTION_ACCOUNT 6

期货委托类型（部分）

常量 值 用途
FUTURE_OPEN_LONG 0 开多
FUTURE_CLOSE_LONG_TODAY 2 平今多
FUTURE_OPEN_SHORT 3 开空
FUTURE_CLOSE_SHORT_TODAY 4 平今空
FUTURE_CLOSE_LONG_HISTORY 6 平昨多
FUTURE_CLOSE_SHORT_HISTORY 7 平昨空

9. 直接 RPC 调用（绕过兼容层）

当兼容层方法不够用时，可直接调 RPC：

from bigqmt_signal_trader.redis_rpc import call_redis_rpc
import redis

r = redis.Redis(host="...", port=6379, db=5, password="...")
resp = call_redis_rpc(r, "ACCOUNT_ID", "get_full_tick", {"codes": ["000001.SZ"]})
print(resp["data"]["000001.SZ"]["lastPrice"])
  • 万能入口: xtdata.call_method("get_float_caps", stockcode="000001.SZ")
  • 方法别名映射:
    • get_full_tick → get_ticks
    • get_instrument_detail → get_instrument
    • query_stock_asset → get_asset
    • query_stock_positions → get_positions
    • query_stock_orders → query_orders
    • query_stock_trades → query_trades
    • order_stock → submit_order
    • cancel_order_stock → cancel_order

RPC 响应结构

{
    "ok": true,
    "data": {...},
    "error": "",
    "server_error": "",
    "handled_at": "2024-07-01 15:00:00"
}
  • ok=true: data 为方法返回值（DataFrame 已序列化，客户端自动还原 pandas 对象）
  • ok=false: error 为错误信息
  • server_error: 额外诊断（如 passorder 提交但委托未进系统）

10. 可用 RPC 方法白名单（117 个只读 + 3 个下单/撤单）

行情快照

get_ticks/get_full_tick, get_instrument/get_instrument_detail, get_instrument_type, get_stock_name, get_stock_type, get_last_close, get_last_volume, get_float_caps, get_total_share, get_turn_over_rate, get_weight_in_index, get_contract_multiplier, get_contract_expire_date, get_open_date, get_svol, get_bvol, get_risk_free_rate, is_stock_type, get_cb_info

K线/历史

get_market_data, get_market_data_ex, get_local_data, get_close_price, get_index_weight

L2 行情（需 L2 权限）

get_l2_quote, get_l2_order, get_l2_transaction, subscribe_l2thousand

板块

get_stock_list_in_sector, get_sector_list, get_sector_info, create_sector, add_sector, remove_sector

交易日历/时段

get_trading_dates, get_holidays, get_markets, get_market_last_trade_date, get_date_location, get_trading_calendar, get_trade_times

数据下载

download_history_data, download_history_data2, download_holiday_data, download_etf_info, download_cb_data, download_history_contracts, download_index_weight, download_sector_data

财务/因子

get_financial_data, download_financial_data, download_financial_data2, get_raw_financial_data, get_factor_data

ETF/期权/期货

get_etf_info, get_ipo_info, get_option_list, get_his_option_list, get_his_option_list_batch, get_option_detail_data, get_option_undl_data, get_option_undl, get_ETF_list, get_main_contract, get_his_contract_list

期权定价

bsm_price, bsm_iv, get_option_iv

龙虎榜/股东

get_longhubang, get_top10_share_holder, get_holder_num, get_turnover_rate, get_industry, get_his_st_data, get_his_index_data

资金流

get_north_finance_change, get_hkt_statistics, get_hkt_details, get_hkt_exchange_rate

因子/模型

call_formula, subscribe_formula, unsubscribe_formula, get_formula_result, gen_factor_index

时间转换（纯本地）

datetime_to_timetag, timetag_to_datetime

账户查询

get_asset, get_positions, query_stock_position, query_orders, query_trades, get_history_trade_detail_data, get_value_by_order_id, get_last_order_id

融资融券（需两融权限）

get_assure_contract, get_enable_short_contract, get_unclosed_compacts, get_closed_compacts, get_debt_contract

期权持仓

get_option_subject_position, get_comb_option

持仓同步

sync_positions

下单/撤单（需开启 rpc_allow_order_methods）

submit_order/order_stock, submit_orders_batch/order_stock_batch, cancel_order/cancel_order_stock/cancel_order_stock_sysid

全推行情

subscribe_whole_quote, unsubscribe_whole_quote, quote_keepalive

Reference in New Issue View Git Blame Copy Permalink