QPro 本地 API 数据结构与字段说明

QPro 本地 API 包含三类数据结构：

• 8811 账户数据服务：查询 QPro 本地节点数据写入的 SQLite 快照表。

• 8812 实时行情服务：通过 SSE 返回完整 Quote JSON 对象，不新增 SQLite 表。

• 8813 合约信息服务：返回合约代码列表或合约信息 JSON 对象，不新增 SQLite 表。

账户数据服务当前提供四张表：

• AccountSnap：账户资金快照。

• PositionSnap：持仓快照。

• OrderSnap：委托快照。

• TradeSnap：成交快照。

账户数据的实际可查询字段可以通过 GET /tables 获取。本文同时说明当前版本的实时行情和合约信息返回结构。

账户数据结构（8811）

刷新机制

QPro 写入线程大约每 500ms 从节点数据库读取一次数据，并按 node_key 对 SQLite 表执行 upsert。表内每行代表一个账户、持仓、委托或成交对象的最新快照。

insert_time 是本地 SQLite 首次插入该行的时间。update_time 是该行最近一次被 QPro upsert 的 SQLite 时间，不等同于交易所事件时间。

账户数据会在账户 ready 后写入，持仓数据会在持仓 ready 后写入。委托和成交按节点数据到达情况写入。

公共字段

字段	含义
node_key	QPro 节点数据中的唯一键，也是各表主键。
insert_time	本地 SQLite 首次插入该行的时间。
update_time	本地 SQLite 最近一次更新该行的时间。
user_key	QPro 内部账户 key。过滤单个账户时优先使用该字段。
investor_id	柜台/经纪商侧投资者账号。
user_desc	QPro 中显示的账户描述。

枚举字段

字段	可能取值
direction	BUY、SELL、INVALID
offset	OPEN、CLOSE、CLOSE_TODAY、CLOSE_YESTERDAY、INVALID
hedge_flag	SPECULATION、ARBITRAGE、HEDGE、MARKET_MAKER、COVERED、SPEC_AND_HEDGE、HEDGE_AND_SPEC、INVALID
price_type	LIMIT、BEST、FIVE_LEVEL、ANY、INVALID
volume_condition	ANY、MIN、ALL、INVALID
time_condition	IOC、GFS、GFD、GTD、GTC、GFA、INVALID
status	ALIVE、DEAD、INVALID
force_close_reason	NOT_FORCE_CLOSE、LACK_DEPOSIT、CLIENT_OVER_POSITION_LIMIT、MEMBER_OVER_POSITION_LIMIT、NOT_MULTIPLE、VIOLATION、OTHER、PERSON_DELIV、HEDGE_OVER_POSITION_LIMIT、OVERSEAS_GROUP_OVER_POSITION_LIMIT、INVALID
ins_class	CONT、FUTURE、OPTION、COMBINE、INDEX、SPOT、STOCK、BOND、FUND、CUS_COMBINE、INVALID

AccountSnap

索引：

• account_update_time_idx(update_time DESC)

• account_user_key_idx(user_key)

字段	含义
currency	币种，默认 CNY。
pre_balance	上日结存。
deposit	入金。
withdraw	出金。
close_profit	平仓盈亏。
position_profit	持仓盈亏。
float_profit	浮动盈亏。
client_equity	客户权益。
balance	账户余额。
margin	当前保证金占用。
frozen_margin	冻结保证金。
commission	手续费。
frozen_commission	冻结手续费。
premium	权利金。
frozen_premium	冻结权利金。
available	可用资金。
risk_ratio	风险度。
ref_risk_ratio	参考风险度。
option_market_value	期权市值。
option_buy_market_value	期权买持市值。
option_sell_market_value	期权卖持市值。
mortgage	质押金额。

PositionSnap

索引：

• position_update_time_idx(update_time DESC)

• position_user_key_idx(user_key)

• position_instrument_id_idx(instrument_id)

字段	含义
exchange_id	交易所代码。
instrument_id	合约代码。
symbol	QPro 行情模型中的 symbol。
product_id	品种代码。
volume_multiple	合约乘数。
last_price	持仓快照使用的最新价。
risk_position	是否风险持仓，1 表示是。
volume_long	多头总持仓。
volume_long_frozen	多头冻结持仓。
volume_short	空头总持仓。
volume_short_frozen	空头冻结持仓。
volume_net	净持仓，通常为多头减空头。
volume_yesterday	昨仓数量。
volume_yesterday_net	昨仓净数量。
volume_total	总持仓数量。
volume_today	今仓数量。
volume_frozen	冻结持仓数量。
volume_comb	组合持仓数量。
volume_long_comb	多头组合持仓数量。
volume_short_comb	空头组合持仓数量。
total_other_position	其他类别持仓总量。
float_profit	浮动盈亏。
position_profit	持仓盈亏。
close_profit	平仓盈亏。
close_profit_by_open	按开仓价计算的平仓盈亏。
margin	该持仓保证金占用。
premium	该持仓权利金。
untrade_profit	未实现/未交易盈亏字段。
trade_profit	交易盈亏字段。
commission	该持仓手续费。
long_market_value	多头市值。
short_market_value	空头市值。
long_market_value_yesterday	昨日多头市值。
short_market_value_yesterday	昨日空头市值。
unit_id	交易单元 id，默认交易单元通常为 0。
ins_class	合约类型。

持仓子字段

PositionSnap 还展开了四组子持仓字段：

• long_spec_：多头投机。

• long_other_：多头其他。

• short_spec_：空头投机。

• short_other_：空头其他。

每组前缀都有以下后缀：

后缀	含义
volume_yesterday	昨仓数量。
volume_today	今仓数量。
volume_his	历史持仓数量。
volume_comb	组合持仓数量。
volume_today_frozen	今仓冻结数量。
volume_his_frozen	历史持仓冻结数量。
strike_frozen	行权/执行冻结数量。
strike_his_frozen	历史行权/执行冻结数量。
open_price	开仓价。
float_profit	浮动盈亏。
position_price	持仓价。
position_profit	持仓盈亏。
close_profit	平仓盈亏。
close_profit_by_open	按开仓价计算的平仓盈亏。
margin	保证金。
market_value	市值。
market_value_yesterday	昨日市值。
commission	手续费。
untrade_profit	未实现/未交易盈亏。
premium	权利金。

例如 long_spec_volume_today、short_other_margin、short_spec_position_profit 都是有效字段。

OrderSnap

索引：

• order_update_time_idx(update_time DESC)

• order_insert_date_time_idx(insert_date_time DESC)

• order_instrument_id_idx(instrument_id)

字段	含义
user_id	柜台侧用户 id。
exchange_id	交易所代码。
instrument_id	合约代码。
symbol	QPro 行情模型中的 symbol。
product_id	品种代码。
volume_multiple	合约乘数。
ins_class	合约类型。
order_id	QPro/源模型委托 id，可与 TradeSnap.order_id 配合 user_key 关联。
is_swap_order	是否互换/换仓相关委托，1 表示是。
is_quote	是否询价/报价相关委托，1 表示是。
hedge_flag	投保标志。
direction	买卖方向。
offset	开平标志。
price_type	价格类型。
limit_price	限价。
volume_orign	原始委托数量。字段名沿用源模型拼写。
volume_left	剩余未成交数量。
volume_trade	已成交数量。
volume_condition	成交量类型。
min_volume	最小成交数量。
time_condition	有效期类型。
status	委托状态。
exchange_order_id	交易所委托编号。
insert_date_time	源模型委托插入时间，BIGINT。
dead_date_time	源模型委托结束时间，BIGINT。
last_trade_date_time	最近成交时间，BIGINT。
status_msg	状态消息。
force_close_reason	强平原因。
user_product_info	用户产品信息。
order_local_id	本地委托编号。
trader_id	交易员代码。
order_ref	报单引用。
front_id	前置编号。
session_id	会话编号。
unit_id	交易单元 id。
seq_no	序号。
flow_index	QPro 源模型流水索引。
request_id	请求编号。
trade_price	委托模型中的成交价格字段。
trade_total_volume	委托模型中的累计成交数量字段。
is_trade_ready	成交信息是否 ready，1 表示 ready。
send_date_time	发送时间，BIGINT。
receive_date_time	接收时间，BIGINT。
memo_user_info	用户备注信息。

TradeSnap

索引：

• trade_update_time_idx(update_time DESC)

• trade_trade_date_time_idx(trade_date_time DESC)

• trade_instrument_id_idx(instrument_id)

字段	含义
user_id	柜台侧用户 id。
exchange_trade_id	交易所成交编号。
exchange_id	交易所代码。
instrument_id	合约代码。
symbol	QPro 行情模型中的 symbol。
product_id	品种代码。
volume_multiple	合约乘数。
ins_class	合约类型。
exchange_order_id	交易所委托编号。
order_id	QPro/源模型委托 id，可与 OrderSnap.order_id 配合 user_key 关联。
direction	买卖方向。
offset	开平标志。
hedge_flag	投保标志。
volume	成交数量。
volume_close_today	平今数量。
volume_close_yesterday	平昨数量。
price	成交价。
trade_date_time	源模型成交时间，BIGINT。
commission	手续费。
order_local_id	本地委托编号。
trader_id	交易员代码。
seq_no	序号。
flow_index	QPro 源模型流水索引。
unit_id	交易单元 id。
memo_user_info	用户备注信息。

实时行情结构（8812）

实时行情服务不写入新的数据库表。客户端通过下面的接口为一个合约建立一个 SSE 连接：

GET /sub_quote/{instrument_id}

每次推送包含一个 quote 事件，data 是服务已经合并好的完整 Quote JSON：

event: quote
data: {"instrument_id":"SHFE.au2612","datetime":"2026-07-14 10:30:00.000000","last_price":782.36}

Quote 主要字段如下：

Quote 字段

字段	类型	含义
instrument_id	string	合约代码，格式为 交易所.合约。
datetime	string	行情更新时间，格式为 YYYY-MM-DD HH:mm:ss.ffffff。
ask_price1 - ask_price10	number/string	卖一到卖十价格。
ask_volume1 - ask_volume10	int	卖一到卖十数量。
bid_price1 - bid_price10	number/string	买一到买十价格。
bid_volume1 - bid_volume10	int	买一到买十数量。
last_price	number/string	当前交易日最新成交价。
highest	number/string	当前交易日最高价。
lowest	number/string	当前交易日最低价。
open	number/string	当前交易日开盘价。
close	number/string	当前交易日收盘价。
average	number/string	当前交易日均价。
volume	int/string	当前交易日成交量。
amount	number/string	当前交易日成交额。
open_interest	int/string	持仓量。
settlement	number/string	当前交易日结算价。
upper_limit	number/string	涨停价。
lower_limit	number/string	跌停价。
pre_open_interest	int/string	上一交易日持仓量。
pre_settlement	number/string	上一交易日结算价。
pre_close	number/string	上一交易日收盘价。

没有有效数值的价格字段可能返回字符串 "-"，部分当前无意义的字段可能不出现在对象中。客户端应按字段是否存在和实际 JSON 类型处理，不要把缺失字段或 "-" 强制转换为 0。

每个 SSE 事件都是完整快照，客户端不需要自行合并上游 DIFF。服务优先保证最新状态；客户端过慢时，中间更新可能被覆盖。

合约信息结构（8813）

合约信息服务同样不写入新的数据库表。所有业务接口都使用 GET，成功响应使用统一外层结构：

{
  "ok": true,
  "data": {}
}

失败响应使用：

{
  "ok": false,
  "error": {
    "code": "BAD_REQUEST",
    "message": "symbol must not be empty"
  }
}

合约与期权列表

GET /query_quotes 和 GET /query_options 都在 data.symbols 中返回合约代码字符串数组：

{
  "ok": true,
  "data": {
    "symbols": ["SHFE.au2612", "SHFE.au2610"]
  }
}

/query_quotes 返回按条件筛选的合约代码，/query_options 返回指定标的的期权代码。它们不返回完整合约属性；需要字段信息时应继续调用 /query_symbol_info。

合约信息对象

GET /query_symbol_info 在 data.items 中返回对象数组，顺序与请求的 symbol 顺序一致：

{
  "ok": true,
  "data": {
    "items": [
      {
        "ins_class": "FUTURE",
        "instrument_id": "SHFE.au2612",
        "instrument_name": "黄金2612",
        "exchange_id": "SHFE",
        "product_id": "au",
        "price_tick": 0.02,
        "volume_multiple": 1000,
        "expired": false
      }
    ]
  }
}

对象字段如下：

合约信息字段

字段	含义
ins_class	合约类型，例如 FUTURE、OPTION、CONT、INDEX。
instrument_id	合约代码。
instrument_name	合约中文名称。
price_tick	最小变动价位。
volume_multiple	合约乘数。
open_limit	日内开仓限额。
max_limit_order_volume	最大限价单手数。
max_market_order_volume	最大市价单手数。
min_limit_order_volume	最小限价单手数。
min_market_order_volume	最小市价单手数。
open_max_market_order_volume	最大市价开仓手数。
open_max_limit_order_volume	最大限价开仓手数。
open_min_market_order_volume	最小市价开仓手数。
open_min_limit_order_volume	最小限价开仓手数。
underlying_symbol	标的合约，主要用于连续合约和期权。
strike_price	期权行权价。
exchange_id	交易所代码。
product_id	品种代码。
expired	是否已到期。
expire_datetime	到期时间，秒级 Unix timestamp。
expire_rest_days	距离到期日的剩余自然日，由服务端根据当前时间计算。
delivery_year	期货交割年份。
delivery_month	期货交割月份。
last_exercise_datetime	期权最后行权时间，秒级 Unix timestamp。
exercise_year	期权最后行权年份，由 last_exercise_datetime 派生。
exercise_month	期权最后行权月份，由 last_exercise_datetime 派生。
option_class	期权方向，CALL 或 PUT。
upper_limit	涨停价。
lower_limit	跌停价。
pre_settlement	上一交易日结算价。
pre_open_interest	上一交易日持仓量。
pre_close	上一交易日收盘价。
trading_time_day	日盘交易时间段。
trading_time_night	夜盘交易时间段。

不适用于某类合约或上游没有提供的字段返回 JSON null。客户端不应把 null 当作 0、空字符串或字符串 "nan"。