.. _qpro_market_schema:

.. rst-class:: qpro-docs-page

================================================================
行情与合约字段
================================================================

.. container:: qpro-docs-meta

   字段说明 · 8812 / 8813 / 8814

本页集中说明 Quote、合约信息和 K 线行的返回字段。请求参数、SSE 行为和查询结果保存方法见 :ref:`qpro_market_data_api`。行情服务的数据结构与账户快照、历史结算记录分别定义。

.. _qpro_quote_fields:

实时行情结构（8812）
=====================

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

.. code-block:: text

    GET /sub_quote/{instrument_id}

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

.. code-block:: text

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

Quote 主要字段如下：

.. list-table:: Quote 字段
   :class: qpro-api-table
   :header-rows: 1
   :widths: 34 20 46

   * - 字段
     - 类型
     - 含义
   * - ``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。服务优先保证最新状态；客户端过慢时，中间更新可能被覆盖。

.. _qpro_instrument_fields:

合约信息结构（8813）
=====================

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

.. code-block:: json

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

失败响应使用：

.. code-block:: json

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

合约与期权列表
--------------

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

.. code-block:: json

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

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

合约信息对象
------------

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

.. code-block:: json

    {
      "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
          }
        ]
      }
    }

对象字段如下：

.. list-table:: 合约信息字段
   :class: qpro-api-table
   :header-rows: 1
   :widths: 36 64

   * - 字段
     - 含义
   * - ``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"``。

.. _qpro_kline_fields:

K 线结构（8814）
================================================================

历史窗口的 ``data.items``、最新窗口 ``snapshot`` 事件的 ``items``，以及增量 ``kline`` 事件的 ``item`` 都包含 K 线行。接口与订阅行为见 :ref:`qpro_market_data_api`。

.. list-table:: K 线行的常用字段
   :class: qpro-api-table
   :header-rows: 1
   :widths: 30 70

   * - 字段
     - 含义
   * - ``id``
     - K 线序号；持续更新时以此覆盖同一根未收盘 K 线
   * - ``datetime``
     - K 线开始时间，Unix 纳秒时间戳
   * - ``open``、``high``、``low``、``close``
     - 开盘价、最高价、最低价和收盘价
   * - ``volume``
     - 该根 K 线的成交量
   * - ``open_oi``、``close_oi``
     - 该根 K 线开始和结束时的持仓量

``datetime`` 的纳秒单位与窗口查询参数 ``focus_time_seconds`` 的秒单位不同。最新一根 K 线在收盘前仍会发生变化。