openapi: 3.0.3
info:
  title: QMT桥接服务接口
  version: 2.0.0
  description: '大 QMT 薄桥 HTTP 接口（主动维护版 OpenAPI 规范）。

    部署在 QMT 策略进程内，端口 8610。

    交易查询数据由策略线程（adjust）缓存刷新，HTTP 线程只读缓存；

    策略名过滤走 QMT 服务端（get_trade_detail_data 第 4 参数）。

    本文件为本地维护的接口规范，可推送至 Apifox 项目（见 tools/push_apifox.py）。

    '
servers:
- url: http://127.0.0.1:8610
  description: QMT 桥接本地服务（远程访问请改为桥所在机器 IP）
paths:
  /health:
    get:
      summary: 健康检查
      description: 桥存活状态 + 账号信息 + 桥版本。
      responses:
        '200':
          description: 成功返回健康信息
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
              example:
                status: ok
                connect_info:
                  mode: big_qmt
                  http_port: 8610
                  ws_port: 8610
                  account: '8882874667'
                last_error: null
                bridge_version: '2'
                hot_reload: true
  /data/kline:
    get:
      summary: K线查询
      description: '查询历史/实时 K 线。查询前自动先下载基础周期（合成周期: 3m←1m,

        10m~4h←5m, 2d~1y←1d）。fields 不传返回完整 OHLCV。

        '
      parameters:
      - name: code
        in: query
        required: true
        schema:
          type: string
        description: 股票代码，600519.SH 或 600519
      - name: period
        in: query
        schema:
          type: string
          default: 1d
        description: tick/1m/5m/15m/30m/60m/1h/1d/1w/1mon
      - name: start
        in: query
        schema:
          type: string
        description: 起始 YYYYMMDD
      - name: end
        in: query
        schema:
          type: string
        description: 结束 YYYYMMDD
      - name: count
        in: query
        schema:
          type: integer
          default: -1
        description: 条数，-1=全部；与 start/end 互斥
      - name: fields
        in: query
        schema:
          type: string
          default: open,high,low,close,volume,amount
        description: '逗号分隔字段。不传=完整 OHLCV。白名单:

          open,high,low,close,volume,amount,settle,openInterest

          '
      responses:
        '200':
          description: K线记录
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KlineResponse'
              example:
                code: 600900.SH
                period: 1d
                count: 14
                data:
                - time: '20260803'
                  open: 28.99
                  high: 29.2
                  low: 28.75
                  close: 29.05
                  volume: 1018010.0
                  amount: 2949045835.0
        '400':
          description: 缺少必填参数（code 未传）或 period 无效
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: code required
  /data/quote:
    get:
      summary: 实时行情快照
      description: '完整快照：最新价、开高低收、昨收、量额、五档盘口。

        底层: ContextInfo.get_full_tick([code])，返回单只股票完整 tick 快照。

        '
      parameters:
      - name: code
        in: query
        required: true
        schema:
          type: string
        description: 股票代码，600519.SH 或 600519
      responses:
        '200':
          description: 完整行情快照（五档盘口）
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuoteResponse'
              example:
                ok: true
                code: 600519.SH
                data:
                  time: 1787209204000
                  timetag: 20260820 15:00:04
                  lastPrice: 1291.5
                  open: 1299.8
                  high: 1306.88
                  low: 1291
                  lastClose: 1307.88
                  amount: 3280474200
                  volume: 25332
                  askPrice:
                  - 1291.58
                  - 1291.61
                  bidPrice:
                  - 1291.5
                  - 1291.49
        '400':
          description: 缺少必填参数（code 未传）
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: code required
  /data/instrument:
    get:
      summary: 合约详细信息（含涨跌停价）
      description: '返回合约详情：UpStopPrice（涨停）/DownStopPrice（跌停）、

        InstrumentName（名称）、OpenDate（上市日期）等。

        底层: ContextInfo.get_instrument_detail。

        '
      parameters:
      - name: code
        in: query
        required: true
        schema:
          type: string
        description: 股票代码，600519.SH 或 600519
      responses:
        '200':
          description: 合约详情
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstrumentResponse'
              example:
                ok: true
                code: 600519.SH
                data:
                  ExchangeID: SH
                  InstrumentID: '600519'
                  InstrumentName: 贵州茅台
                  OpenDate: 20010827
                  PreClose: 1307.88
                  UpStopPrice: 1438.67
                  DownStopPrice: 1177.09
                  PriceTick: 0.01
        '400':
          description: 缺少必填参数（code 未传）
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: code required
  /data/calendar/trading_dates:
    get:
      summary: 交易日历
      description: '返回 [start, end] 区间内的交易日列表（YYYYMMDD 字符串）。

        底层: ContextInfo.get_trading_dates。可用于市场活跃判断。

        '
      parameters:
      - name: start
        in: query
        schema:
          type: string
        description: 起始 YYYYMMDD
      - name: end
        in: query
        schema:
          type: string
        description: 结束 YYYYMMDD
      responses:
        '200':
          description: 交易日列表
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TradingDatesResponse'
              example:
                market: SH
                count: 3
                dates:
                - '20260818'
                - '20260819'
                - '20260820'
  /data/subscribe:
    post:
      summary: 订阅数据（全量tick）
      description: '订阅数据推送类型。当前支持 whole（全量tick增量推送）。

        订阅成功后返回 sub_id，WS 连接 ws://host:8610/ws 接收推送。

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscribeRequest'
            example:
              type: whole
              codes:
              - SH
              - SZ
      responses:
        '200':
          description: 订阅成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscribeResponse'
              example:
                ok: true
                sub_id: 7322465032736768
        '400':
          description: 参数错误（unsupported type / codes required / invalid json）
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: codes required
        '503':
          description: 订阅失败（QMT subscribe_whole_quote 失败）
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: subscribe_whole_quote failed for codes=['SH', 'SZ']
  /data/unsubscribe:
    post:
      summary: 退订数据
      description: 按 sub_id 退订某类型的订阅。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UnsubscribeRequest'
            example:
              sub_id: 7322465032736768
      responses:
        '200':
          description: 退订成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnsubscribeResponse'
              example:
                ok: true
        '404':
          description: 订阅ID不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: sub_id not found
  /data/tick:
    get:
      summary: 获取全推tick快照
      description: '透传 ContextInfo.get_full_tick(codes)，返回指定代码的最新分笔快照。

        客户端需要当前快照时主动调用（WS 只推增量，不做 prime 推送）。

        '
      parameters:
      - name: codes
        in: query
        required: true
        schema:
          type: string
        description: 逗号分隔代码列表，如 600000.SH,000001.SZ
      responses:
        '200':
          description: 快照数据
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TickBatchResponse'
              example:
                ok: true
                data:
                  600000.SH:
                    timetag: 20231106 15:00:04
                    lastPrice: 2.533
                    volume: 5701929
        '400':
          description: codes 缺失
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: codes required
  /trade/positions:
    get:
      summary: 持仓查询
      description: '当前账号全部持仓（语义化字段 + 原始 m_* 字段超集 + 汇总 summary）。

        账号为桥绑定账号（单账号策略），无需传 account 参数。

        不做过滤筛选：返回全部持仓，客户端按需自取。

        数据由策略线程（adjust）每 300ms 缓存刷新，HTTP 线程只读缓存。

        '
      parameters: []
      responses:
        '200':
          description: 全部持仓 + 汇总
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PositionsResponse'
              example:
                ok: true
                data:
                  positions:
                  - stock_code: 600519.SH
                    stock_name: 贵州茅台
                    volume: 100
                    available: 100
                    frozen_volume: 0
                    on_road_volume: 0
                    yesterday_volume: 0
                    avg_price: 1500.0
                    price: 1510.0
                    market_value: 151000.0
                    open_price: 1500.0
                    profit: 1000.0
                    profit_pct: 0.67
                    direction: 48
                    m_strInstrumentID: '600519'
                    m_strInstrumentName: 贵州茅台
                    m_nVolume: 100
                    m_nCanUseVolume: 100
                    m_dOpenPrice: 1500.0
                    m_dFloatProfit: 1000.0
                  summary:
                    count: 1
                    total_market_value: 151000.0
                    total_profit: 1000.0
  /trade/asset:
    get:
      summary: 资金资产查询
      description: '资金账号资产信息（m_* 原始字段）。

        账号为桥绑定账号（单账号策略），无需传 account 参数。

        数据由策略线程（adjust）每 300ms 缓存刷新，HTTP 线程只读缓存。

        '
      parameters: []
      responses:
        '200':
          description: 资产信息
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetResponse'
              example:
                ok: true
                data:
                - m_strAccountID: '8882874667'
                  m_dBalance: 126244.05
                  m_dAvailable: 31669.54
                  m_dAssetBalance: 126244.05
                  m_dFrozenCash: 3400.714
  /trade/orders:
    get:
      summary: 当日委托查询（支持过滤）
      description: '当日委托列表（m_* 原始字段）。账号为桥绑定账号（单账号策略），

        无需传 account 参数。支持三类过滤：

        - code: 客户端按代码过滤（600519 或 600519.SH）

        - status: active（排除已撤54/废单57）或具体状态码

        - strategy_name: QMT 服务端按 passorder 策略名过滤

        （remark 过滤暂未实现）

        数据由策略线程（adjust）每 300ms 缓存刷新，HTTP 线程只读缓存。

        '
      parameters:
      - name: code
        in: query
        schema:
          type: string
        description: 股票代码过滤（600519 或 600519.SH）
      - name: status
        in: query
        schema:
          type: string
        description: active=排除已撤(54)/废单(57)；或数字状态码如 50/48/56
      - name: strategy_name
        in: query
        schema:
          type: string
        description: QMT 服务端按策略名过滤（passorder 时传入的名字）
      responses:
        '200':
          description: 委托列表
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrdersResponse'
              example:
                ok: true
                data:
                - m_strOrderSysID: '645000387'
                  m_strAccountID: '8882874667'
                  m_strExchangeID: SH
                  m_strInstrumentID: '601117'
                  m_strInstrumentName: 中国化学
                  m_nDirection: 48
                  m_nOrderStatus: 50
                  m_nVolumeTotalOriginal: 200
                  m_nVolumeTraded: 0
                  m_nVolumeTotal: 200
                  m_dLimitPrice: 7.0
                  m_strInsertTime: 09:30:01
                  m_dTradedPrice: 0.0
  /trade/trades:
    get:
      summary: 当日成交查询
      description: '当日成交列表（m_* 原始字段）。

        账号为桥绑定账号（单账号策略），无需传 account 参数。

        数据由策略线程（adjust）每 300ms 缓存刷新，HTTP 线程只读缓存。

        '
      parameters: []
      responses:
        '200':
          description: 成交列表
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TradesResponse'
              example:
                ok: true
                data:
                - m_strTradeID: '14212286'
                  m_strOrderSysID: '645006675'
                  m_strAccountID: '8882874667'
                  m_strExchangeID: SH
                  m_strInstrumentID: '600719'
                  m_strInstrumentName: 大连热电
                  m_nDirection: 48
                  m_dPrice: 7.03
                  m_nVolume: 400
                  m_strTradeDate: '20260826'
                  m_strTradeTime: 094648
                  m_dCommission: 2.0
                  m_dTradeAmount: 2812.0
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        detail:
          type: string
          description: 错误信息
      required:
      - detail
    SubscribeRequest:
      type: object
      properties:
        type:
          type: string
          description: 订阅类型，当前支持 whole
        codes:
          type: array
          items:
            type: string
          description: 代码列表，如 ['SH','SZ']
    UnsubscribeRequest:
      type: object
      properties:
        sub_id:
          type: integer
          description: 订阅ID（订阅接口返回）
    HealthResponse:
      type: object
      properties:
        status:
          type: string
          description: 服务状态（ok=正常）
        connect_info:
          type: object
          description: 连接信息
          properties:
            mode:
              type: string
              description: 运行模式（big_qmt=大 QMT）
            http_port:
              type: integer
              description: HTTP 端口
            ws_port:
              type: integer
              description: WebSocket 端口
            account:
              type: string
              description: 桥绑定资金账号
        last_error:
          type: string
          nullable: true
          description: 最近一次错误（无则为 null）
        bridge_version:
          type: string
          description: 桥版本
        hot_reload:
          type: boolean
          description: 是否支持热重载
    KlineResponse:
      type: object
      properties:
        code:
          type: string
          description: 完整证券代码
        period:
          type: string
          description: K线周期
        count:
          type: integer
          description: 返回条数
        data:
          type: array
          description: K线记录列表
          items:
            $ref: '#/components/schemas/KlineBar'
    QuoteResponse:
      type: object
      properties:
        ok:
          type: boolean
          description: 是否成功
        code:
          type: string
          description: 完整证券代码
        data:
          $ref: '#/components/schemas/TickSnapshot'
    InstrumentResponse:
      type: object
      properties:
        ok:
          type: boolean
          description: 是否成功
        code:
          type: string
          description: 完整证券代码
        data:
          $ref: '#/components/schemas/InstrumentDetail'
    TradingDatesResponse:
      type: object
      properties:
        market:
          type: string
          description: 市场（SH）
        count:
          type: integer
          description: 交易日数量
        dates:
          type: array
          description: 交易日列表（YYYYMMDD 字符串）
          items:
            type: string
    SubscribeResponse:
      type: object
      properties:
        ok:
          type: boolean
          description: 是否成功
        sub_id:
          type: integer
          description: 订阅ID（退订时使用，snowflake 类唯一 ID）
    UnsubscribeResponse:
      type: object
      properties:
        ok:
          type: boolean
          description: 是否成功
    TickBatchResponse:
      type: object
      properties:
        ok:
          type: boolean
          description: 是否成功
        data:
          type: object
          description: 代码 → tick 快照字典
          additionalProperties:
            $ref: '#/components/schemas/TickSnapshot'
    PositionsResponse:
      type: object
      properties:
        ok:
          type: boolean
          description: 是否成功
        data:
          type: object
          description: 持仓数据
          properties:
            positions:
              type: array
              description: 持仓列表（每行 = 语义化字段 + 原始 m_* 字段）
              items:
                $ref: '#/components/schemas/Position'
            summary:
              $ref: '#/components/schemas/PositionSummary'
    AssetResponse:
      type: object
      properties:
        ok:
          type: boolean
          description: 是否成功
        data:
          type: array
          description: 资产行（通常 1 行）
          items:
            $ref: '#/components/schemas/Asset'
    OrdersResponse:
      type: object
      properties:
        ok:
          type: boolean
          description: 是否成功
        data:
          type: array
          description: 委托列表
          items:
            $ref: '#/components/schemas/Order'
    TradesResponse:
      type: object
      properties:
        ok:
          type: boolean
          description: 是否成功
        data:
          type: array
          description: 成交列表
          items:
            $ref: '#/components/schemas/Trade'
    KlineBar:
      type: object
      properties:
        time:
          type: string
          description: 时间（日线为 YYYYMMDD，分钟线为时间戳/时间串）
        open:
          type: number
          description: 开盘价
        high:
          type: number
          description: 最高价
        low:
          type: number
          description: 最低价
        close:
          type: number
          description: 收盘价
        volume:
          type: number
          description: 成交量
        amount:
          type: number
          description: 成交额
        settle:
          type: number
          description: 结算价（可选字段）
        openInterest:
          type: number
          description: 持仓量/未平仓合约（可选字段）
    TickSnapshot:
      type: object
      description: tick 快照字段
      properties:
        time:
          type: integer
          description: 行情时间戳（毫秒）
        timetag:
          type: string
          description: 行情时间（可读格式，如 20260820 15:00:04）
        lastPrice:
          type: number
          description: 最新价
        open:
          type: number
          description: 今开
        high:
          type: number
          description: 最高
        low:
          type: number
          description: 最低
        lastClose:
          type: number
          description: 昨收
        amount:
          type: number
          description: 成交额（元）
        volume:
          type: integer
          description: 成交量（股）
        pvolume:
          type: integer
          description: 成交笔数（或同 volume）
        askPrice:
          type: array
          description: 卖五档价格（askPrice[0]=卖一）
          items:
            type: number
        askVol:
          type: array
          description: 卖五档量
          items:
            type: integer
        bidPrice:
          type: array
          description: 买五档价格（bidPrice[0]=买一）
          items:
            type: number
        bidVol:
          type: array
          description: 买五档量
          items:
            type: integer
        stockStatus:
          type: integer
          description: 股票状态
    InstrumentDetail:
      type: object
      description: 合约详情字段
      properties:
        ExchangeID:
          type: string
          description: 交易所（SH/SZ）
        InstrumentID:
          type: string
          description: 合约代码（不带后缀）
        InstrumentName:
          type: string
          description: 合约/证券名称
        OpenDate:
          type: string
          description: 上市日期（YYYYMMDD）
        PreClose:
          type: number
          description: 昨收盘价
        UpStopPrice:
          type: number
          description: 涨停价
        DownStopPrice:
          type: number
          description: 跌停价
        PriceTick:
          type: number
          description: 最小价格变动单位
    Position:
      type: object
      properties:
        stock_code:
          type: string
          description: 完整证券代码（带交易所后缀，如 600519.SH）
        stock_name:
          type: string
          description: 证券名称
        volume:
          type: integer
          description: 当前持仓量（股）
        available:
          type: integer
          description: 可用数量（可卖数量，股）
        frozen_volume:
          type: integer
          description: 冻结数量（股）
        on_road_volume:
          type: integer
          description: 在途股份（股）
        yesterday_volume:
          type: integer
          description: 昨仓数量（股）
        avg_price:
          type: number
          description: 持仓成本价 = (总买入金额-总卖出金额)/剩余数量
        open_price:
          type: number
          description: 开仓均价（与 avg_price 同源）
        price:
          type: number
          description: 最新价（缺失时兜底为成本价）
        market_value:
          type: number
          description: 持仓市值（元）；缺失时按 volume*price 计算
        profit:
          type: number
          description: 浮动盈亏（元）；缺失时按 (price-avg_price)*volume 计算
        profit_pct:
          type: number
          description: 浮动盈亏比例（%）
        direction:
          type: integer
          description: 买卖方向（股票恒为 48=买入/多）
        m_strInstrumentID:
          type: string
          description: '[原始字段] 证券代码（不带后缀，如 600519）'
        m_strInstrumentName:
          type: string
          description: '[原始字段] 证券名称'
        m_nVolume:
          type: integer
          description: '[原始字段] 当前拥股/持仓量'
        m_nCanUseVolume:
          type: integer
          description: '[原始字段] 可用数量'
        m_dOpenPrice:
          type: number
          description: '[原始字段] 持仓成本'
        m_dFloatProfit:
          type: number
          description: '[原始字段] 浮动盈亏'
    PositionSummary:
      type: object
      description: 汇总信息
      properties:
        count:
          type: integer
          description: 持仓只数
        total_market_value:
          type: number
          description: 总市值（元）
        total_profit:
          type: number
          description: 总浮动盈亏（元）
    Asset:
      type: object
      properties:
        m_strAccountID:
          type: string
          description: 资金账号
        m_dBalance:
          type: number
          description: 总资产（账户总资金金额）
        m_dAvailable:
          type: number
          description: 可用金额（可交易和提取的资金）
        m_dAssetBalance:
          type: number
          description: 证券初始资金（股票账户初始资金）
        m_dFrozenCash:
          type: number
          description: 冻结金额（被冻结的资金）
        m_dInstrumentValue:
          type: number
          description: 总市值（持有证券的总市值）
        m_dStockValue:
          type: number
          description: 股票总市值
        m_dPositionProfit:
          type: number
          description: 持仓盈亏
        m_dFetchBalance:
          type: number
          description: 可取金额
        m_dCashIn:
          type: number
          description: 出入金净值
        m_strTradingDate:
          type: string
          description: 交易日
    Order:
      type: object
      properties:
        m_strOrderSysID:
          type: string
          description: 合同编号/委托号（撤单凭此号）
        m_strAccountID:
          type: string
          description: 资金账号
        m_strExchangeID:
          type: string
          description: 证券市场（SH/SZ）
        m_strInstrumentID:
          type: string
          description: 证券代码（不带后缀，如 601117）
        m_strInstrumentName:
          type: string
          description: 证券名称
        m_nDirection:
          type: integer
          description: 买卖方向（股票恒为 48）
        m_nOrderStatus:
          type: integer
          description: 委托状态码：48=未报, 49=待报, 50=已报(待成交), 51=已报待撤, 52=部成待撤, 53=部撤, 54=已撤, 55=部成, 56=已成, 57=废单
        m_nVolumeTotalOriginal:
          type: integer
          description: 委托数量（最初委托数量）
        m_nVolumeTraded:
          type: integer
          description: 成交数量（已成交量）
        m_nVolumeTotal:
          type: integer
          description: 委托剩余量（总委托量-成交量）
        m_dLimitPrice:
          type: number
          description: 委托价格（限价单的限价）
        m_strInsertDate:
          type: string
          description: 委托日期
        m_strInsertTime:
          type: string
          description: 委托时间
        m_dTradedPrice:
          type: number
          description: 成交均价（股票）
        m_strErrorMsg:
          type: string
          description: 状态信息/错误信息
        m_strCancelInfo:
          type: string
          description: 废单原因
        m_strRemark:
          type: string
          description: 投资备注（大 QMT 订单行通常无此字段，服务端过滤）
    Trade:
      type: object
      properties:
        m_strTradeID:
          type: string
          description: 成交编号
        m_strOrderSysID:
          type: string
          description: 合同编号/委托号（与委托表同号，用于关联）
        m_strAccountID:
          type: string
          description: 资金账号
        m_strExchangeID:
          type: string
          description: 证券市场（SH/SZ）
        m_strInstrumentID:
          type: string
          description: 证券代码（不带后缀，如 600719）
        m_strInstrumentName:
          type: string
          description: 证券名称
        m_nDirection:
          type: integer
          description: 买卖方向（股票恒为 48）
        m_dPrice:
          type: number
          description: 成交均价
        m_nVolume:
          type: integer
          description: 成交量（股）
        m_strTradeDate:
          type: string
          description: 成交日期
        m_strTradeTime:
          type: string
          description: 成交时间
        m_dCommission:
          type: number
          description: 手续费
        m_dTradeAmount:
          type: number
          description: 成交额
        m_strRemark:
          type: string
          description: 投资备注