实时行情、K 线与合约信息 API

概述

QPro 本地 API 提供实时行情、K 线与历史行情和合约信息服务。合约信息服务用于发现有效合约、查询期权列表和读取合约属性；实时行情服务用于按合约订阅最新 Quote；K 线与历史行情服务既能持续推送最新 K 线窗口，也能查询指定时间附近的历史 K 线或下载历史行情。三个服务都由 QPro 自动启动和维护，用户不需要单独运行程序或填写访问令牌。

服务地址
服务	默认地址	作用
实时行情	`http://127.0.0.1:8812`	通过 SSE 持续推送单个合约的最新行情快照
合约信息	`http://127.0.0.1:8813`	查询合约列表、期权列表和合约属性
K 线与历史行情	`http://127.0.0.1:8814`	持续推送最新 K 线或 Tick，查询历史窗口，并下载 CSV/ZIP 行情文件

使用前提

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

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

三个请求都应返回：

{"ok": true}

如果在 QPro 中修改过端口，请同步替换本文示例中的 8812、8813 和 8814。8814 只有在上游历史行情连接可用时才会返回 HTTP 200；暂时断线时返回 HTTP 503 和 {"ok": false}。

合约代码格式

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

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

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

查询合约信息

合约信息服务只接受 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 的客户端。

获取实时和历史 K 线

K 线与历史行情服务使用默认地址 http://127.0.0.1:8814。同一个服务提供两种互补的 K 线能力：

/stream/klines/latest 持续推送最新窗口，适合实时 K 线图、指标看板和监控。
/klines 一次返回指定时间附近的历史窗口，适合交易复盘和研究。

K 线周期参数 duration_seconds 使用秒，例如 60 表示 1 分钟、300 表示 5 分钟。返回行中的 datetime 是 Unix 纳秒时间戳；不要与查询参数使用的 Unix 秒时间戳混淆。

订阅最新 K 线

最新 K 线接口使用 SSE：

GET /stream/klines/latest?instrument_id={instrument_id}&duration_seconds={seconds}&count={count}

例如，持续接收某合约最新 200 根 1 分钟 K 线：

curl.exe -N "http://127.0.0.1:8814/stream/klines/latest?instrument_id=SHFE.au2612&duration_seconds=60&count=200"

连接建立后，服务先发送完整窗口：

event: snapshot
data: {"instrument_id":"SHFE.au2612","duration_seconds":60,"items":[...]}

之后发送发生变化的单根 K 线：

event: kline
data: {"instrument_id":"SHFE.au2612","duration_seconds":60,"item":{"id":1375259,"datetime":1784098740000000000,"open":879.94,"high":880.10,"low":879.88,"close":880.10,"volume":432,"open_oi":112816,"close_oi":112745}}

count 范围为 1 至 1000。同一个 id 可能被多次推送，表示当前未收盘 K 线又发生了变化；客户端应以 id 为键覆盖旧值，只保留最新 count 根。新 K 线产生时会出现新的 id。服务还会发送 : ping 注释作为心跳，客户端可以忽略。

查询历史 K 线窗口

历史窗口接口围绕一个焦点时间返回最多 1000 根 K 线：

GET /klines?instrument_id={instrument_id}&duration_seconds={seconds}&focus_time_seconds={unix_seconds}&focus_position={position}&count={count}

例如，查询指定时间开始的 200 根 1 分钟 K 线：

Invoke-RestMethod "http://127.0.0.1:8814/klines?instrument_id=SHFE.au2612&duration_seconds=60&focus_time_seconds=1784000000&focus_position=0&count=200"

`/klines` 参数
参数	示例	说明
`instrument_id`	`SHFE.au2612`	单个合约代码，使用 `交易所.合约` 格式
`duration_seconds`	`60`	K 线周期，必须为正整数秒
`focus_time_seconds`	`1784000000`	焦点时间，Unix 秒级时间戳
`focus_position`	`0`	焦点在返回窗口中的位置，范围为 `0` 至 `count - 1`
`count`	`200`	返回窗口大小，范围为 `1` 至 `1000`

成功响应中的 data.items 按 id 升序排列。每行常见字段包括 id、datetime、open、high、low、close、volume、open_oi 和 close_oi。已完成但没有数据的窗口返回空数组 items: []。

备注

指定历史时间的一次性 /klines 和 /ticks 查询要求当前 QPro 账号具备多账户功能权限。权限不足时返回 HTTP 403，错误码为 FEATURE_REQUIRED。最新 K 线与 Tick 的 SSE 流不受这项单次历史查询限制；最终可用数据范围仍取决于当前账号的行情与历史数据权限。

下载历史行情文件

需要更长时间范围或多个合约时，可以使用 POST /csv 下载 CSV 或 ZIP。单个合约返回 CSV，download_list 批量请求返回 ZIP；QPro 会自动使用当前登录身份访问上游，调用方不要自行传入访问令牌。

$body = @{
  aid = "download"
  symbol = "SHFE.au2612"
  duration = 60000000000
  datetime_begin = 1783987200000000000
  datetime_end = 1784073600000000000
} | ConvertTo-Json
Invoke-WebRequest http://127.0.0.1:8814/csv -Method Post -ContentType "application/json" -Body $body -OutFile data.csv

下载接口中的 duration、datetime_begin 和 datetime_end 都使用纳秒。推荐安装 QPro 附带的实时与历史 K 线 skill，让 Agent 按正确的时间单位、周期规则和返回格式生成请求。

组合使用示例

下面的 PowerShell 示例先查询一个当前未到期的上期所黄金期货，再读取合约属性，同时订阅它的实时 Quote 和最新 1 分钟 K 线：

$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"
curl.exe -N "http://127.0.0.1:8814/stream/klines/latest?instrument_id=$symbol&duration_seconds=60&count=200"

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

能力边界与安全

实时行情服务提供最新 Quote，K 线与历史行情服务提供 K 线、Tick 和历史文件，合约信息服务提供合约元数据。它们都不能下单、撤单或改单，也不负责把查询结果持久化到本地数据库。

三个服务只监听本机 localhost，调用接口时不再要求单独提供访问令牌。不要通过端口转发或反向代理把服务暴露到不可信网络，也不要把返回的账户或行情数据交给不受信任的程序。QPro 仍会以当前登录身份访问上游，并按账号功能与数据权限控制可用范围。