.. _qpro_market_data_api:

===========================
实时行情与合约信息 API
===========================

概述
====

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

.. list-table:: 服务地址
   :header-rows: 1
   :widths: 25 20 55

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

使用前提
========

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

.. code-block:: powershell

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

两个请求都应返回：

.. code-block:: json

    {"ok": true}

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

合约代码格式
============

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

.. code-block:: text

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

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

查询合约信息
============

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

.. code-block:: json

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

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

.. code-block:: json

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

查询合约列表
------------

接口：

.. code-block:: text

    GET /query_quotes

常用参数：

.. list-table:: ``/query_quotes`` 参数
   :header-rows: 1
   :widths: 25 20 55

   * - 参数
     - 示例
     - 说明
   * - ``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``。

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

.. code-block:: powershell

    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``。

查询期权列表
------------

接口：

.. code-block:: text

    GET /query_options

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

.. code-block:: powershell

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

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

查询合约属性
------------

接口：

.. code-block:: text

    GET /query_symbol_info

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

.. code-block:: powershell

    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 和合约信息字段表见 :ref:`qpro_httpserver_schema`。

订阅实时行情
============

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

.. code-block:: text

    GET /sub_quote/{instrument_id}

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

.. code-block:: powershell

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

服务会持续输出：

.. code-block:: text

    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 示例先查询一个当前未到期的上期所黄金期货，再读取合约属性并订阅它的实时行情：

.. code-block:: 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``，调用接口时不再要求单独鉴权。不要通过端口转发或反向代理把服务暴露到不可信网络，也不要把返回的账户或行情数据交给不受信任的程序。