实时行情与合约信息 API

概述

QPro 本地 API 新增了实时行情服务和合约信息服务。合约信息服务用于发现有效合约、查询期权列表和读取合约属性；实时行情服务用于按合约订阅最新行情。两个服务都由 QPro 自动启动和维护，用户不需要单独运行程序或填写访问令牌。

服务地址
服务	默认地址	作用
实时行情	`http://127.0.0.1:8812`	通过 SSE 持续推送单个合约的最新行情快照
合约信息	`http://127.0.0.1:8813`	查询合约列表、期权列表和合约属性

使用前提

先按照 QPro 本地 API 使用说明中的说明启用本地 API，重启并登录 QPro。可以用下面的命令检查服务：

Invoke-RestMethod http://127.0.0.1:8812/health
Invoke-RestMethod http://127.0.0.1:8813/health

两个请求都应返回：

{"ok": true}

如果在 QPro 中修改过端口，请同步替换本文示例中的 8812 和 8813。

合约代码格式

两个服务都使用 交易所.合约 格式的合约代码，例如：

SHFE.au2612
DCE.m2609
CZCE.FG605
CFFEX.IF2607
SSE.510050
SZSE.159915

推荐先通过合约信息服务查询当前有效的合约代码，再订阅实时行情。示例中的具体合约可能随着时间推移而到期。

查询合约信息

合约信息服务只接受 GET 请求，参数放在 URL query string 中。成功响应格式为：

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

参数错误或上游查询异常时，响应格式为：

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

查询合约列表

接口：

GET /query_quotes

常用参数：

`/query_quotes` 参数
参数	示例	说明
`ins_class`	`FUTURE`	合约类型；可以用英文逗号传多个值
`exchange_id`	`SHFE`	交易所；可以用英文逗号传多个值
`product_id`	`au`	品种代码；可以用英文逗号传多个值
`expired`	`false`	是否已到期，只接受 `true` 或 `false`
`has_night`	`true`	是否有夜盘，只接受 `true` 或 `false`

常用 ins_class 包括 FUTURE、CONT、COMBINE、INDEX、OPTION、STOCK、FUND、BOND、SPOT。

例如，查询上期所未到期的黄金期货：

Invoke-RestMethod "http://127.0.0.1:8813/query_quotes?ins_class=FUTURE&exchange_id=SHFE&product_id=au&expired=false"

返回的 data.symbols 是合约代码列表。该接口不返回完整属性；需要价格最小变动单位、合约乘数或到期日时，再调用 /query_symbol_info。

查询期权列表

接口：

GET /query_options

underlying_symbol 是必填的标的合约；option_class 可选 CALL 或 PUT，不传时返回该标的的全部期权。

Invoke-RestMethod "http://127.0.0.1:8813/query_options?underlying_symbol=SHFE.au2612&option_class=CALL"

返回的 data.symbols 是期权合约代码列表。标的不存在或没有对应期权时返回空列表，不会把它视为服务错误。

查询合约属性

接口：

GET /query_symbol_info

symbol 是必填参数，可以传一个合约，也可以用英文逗号分隔多个合约：

Invoke-RestMethod "http://127.0.0.1:8813/query_symbol_info?symbol=SHFE.au2612,DCE.m2609"

返回的 data.items 与请求顺序一致。常用字段包括：

instrument_id、instrument_name、exchange_id、product_id、ins_class
price_tick、volume_multiple
expired、expire_datetime、expire_rest_days
underlying_symbol、strike_price、option_class
upper_limit、lower_limit、pre_settlement、pre_open_interest、pre_close
trading_time_day、trading_time_night
限价单、市价单的最大和最小下单手数限制

某个字段没有可用值时，服务返回 JSON null。不要把 null 当作 0 或空字符串。

完整 Quote 和合约信息字段表见 QPro 本地 API 数据结构与字段说明。

订阅实时行情

实时行情接口使用 Server-Sent Events（SSE）。每个 HTTP 连接订阅一个合约：

GET /sub_quote/{instrument_id}

在 PowerShell 中建议使用不会缓冲输出的 curl.exe -N：

curl.exe -N http://127.0.0.1:8812/sub_quote/SHFE.au2612

服务会持续输出：

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

每个 event: quote 后面的 data: 都是服务已经合并好的完整 Quote 快照。常见字段包括最新价、开高低收、成交量、成交额、持仓量、涨跌停价，以及买一到买十、卖一到卖十的价格和数量。

使用实时行情时需要注意：

每个 HTTP 连接只订阅一个合约；多个合约需要建立多个连接。
如果服务已有该合约的本地快照，连接建立后会立即发送当前快照。
服务优先保证最新状态；客户端过慢时，中间行情更新可能被丢弃。
无效或不活跃合约可能保持连接但没有有效行情事件，客户端应自行设置超时。
QPro 重启后，客户端需要重新建立 SSE 连接。
Invoke-RestMethod 适合检查 /health，不适合长期读取 SSE；命令行请使用 curl.exe -N，程序中请使用支持 SSE 的客户端。

组合使用示例

下面的 PowerShell 示例先查询一个当前未到期的上期所黄金期货，再读取合约属性并订阅它的实时行情：

$result = Invoke-RestMethod "http://127.0.0.1:8813/query_quotes?ins_class=FUTURE&exchange_id=SHFE&product_id=au&expired=false"
$symbol = $result.data.symbols[0]
Invoke-RestMethod "http://127.0.0.1:8813/query_symbol_info?symbol=$symbol"
curl.exe -N "http://127.0.0.1:8812/sub_quote/$symbol"

本地 Agent 可以在这个流程上继续完成合约筛选、行情监控、提醒或看板生成。如果需要把行情和持仓关联，可以再读取 8811 的账户数据接口。

能力边界与安全

实时行情服务只提供行情，合约信息服务只提供合约元数据。它们都不能下单、撤单或改单。

两个服务只监听本机 localhost，调用接口时不再要求单独鉴权。不要通过端口转发或反向代理把服务暴露到不可信网络，也不要把返回的账户或行情数据交给不受信任的程序。