Orange Hitick 波动率数据 Skill 文档

这份文档用于开发者手动接入，或让 Agent 按统一规则接入 Orange Hitick 的波动率数据服务。

1. 服务信息

• 平台接口前缀：/api/v1/vol-data
• 鉴权方式：请求头 X-API-Token
• 返回包装：Orange Hitick 统一 ApiResponse
• 当前服务编码：vol_data
• 当前服务名称：波动率数据
• 计费说明：/groups 不计费；/query/*、/snapshot/*、/ts/*、/gex/*、/gex-image/* 成功返回后计费，扣费失败则接口直接返回错误

平台统一返回结构：

{
  "code": 0,
  "message": "success",
  "data": {}
}

说明：

• code = 0 表示平台调用成功
• 真正的波动率数据结果放在 data 中
• data 是上游接口返回结果的透传 JSON

2. 鉴权

所有请求都必须带：

X-API-Token: your_token_value

为减少大 JSON 的传输量，HTTP 客户端可发送 Accept-Encoding: gzip。服务端协商压缩后返回 Content-Encoding: gzip，客户端应解压后再解析 JSON；例如 curl --compressed 会自动完成协商和解压。不声明支持 gzip 时仍返回原文，返回结构和查询范围限制不变。

3. 接口能力总览

本服务可以提供 6 大类数据能力：

1. 分组目录：可查询哪些 (underlying, expire_date, multiplier) 组合当前可用
2. 实时快照：可查询标的报价、ATM 隐波、期权链、Greeks、盘口隐波、卖方保证金
3. 历史小时快照：可查询本地落库的 T 型报价小时快照
4. 时序数据：可查询某一时间区间内的 atm_iv 与标的价格走势
5. GEX 曲线与 GEX 小时快照：可查询 Gamma Exposure 分布、当前净 GEX、零 gamma 位置，并可回看本地落库的小时 GEX 快照
6. Agent / MCP 接入：先用 orange_resolve_subject 解析标的，实时快照统一使用 by_underlying，并支持 snapshot_*、ts_*、gex_* 标准化动作

建议使用顺序：

1. Agent 中先用 orange_resolve_subject 把中文品种名、代码前缀或不完整合约解析成标准三元组
2. 查询实时快照时优先使用 query/*
3. 查询历史整点快照时使用 snapshot/*
4. 查询波动率走势时使用 ts/*
5. 查询 Gamma Exposure 分布时使用 gex/*
6. 查询历史整点 GEX 结构时使用 gex/snapshot/*

REST 的 /groups 接口仍保持不变，供原有 HTTP 客户端使用；Raw MCP 不公开全量分组 action。

4. 接口列表与请求参数

4.1 获取缓存分组

GET /api/v1/vol-data/groups

用途：

• 返回当前可查询的 (underlying, expire_date, multiplier) 组合
• 适合在已知标的代码后，进一步确认有哪些到期日和合约乘数可查
• 不扣费

请求参数：

• 无 query 参数

示例：

curl -sS 'https://api.hitick.top/api/v1/vol-data/groups' \
  -H 'X-API-Token: your_token_value'

返回核心结构：

{
  "groups": [
    {
      "underlying": "au2607",
      "expire_date": "20260624",
      "multiplier": 1000
    }
  ]
}

字段说明：

• groups[].underlying：标的代码
• groups[].expire_date：到期日，格式 yyyyMMdd
• groups[].multiplier：合约乘数

4.2 实时快照接口

实时快照接口用于查询某个标的分组下的完整 T 型报价快照，包含：

• 标的最新报价
• 当前 ATM 隐含波动率
• 隐含波动率偏度（iv_skew）
• PCR 指标（oi_pcr、volume_pcr）
• 行权价维度的期权链
• Call / Put 双边 Greeks
• 理论隐波、盘口隐波
• 卖方参考保证金

4.2.1 按标的查询

GET /api/v1/vol-data/query/by-underlying?underlying=au2607

必填参数：

• underlying：标的代码，例如 au2607

可选参数：

• expire：到期日，格式 yyyyMMdd
• multiplier：合约乘数，例如 1000

适用场景：

• 只知道标的代码，想拿当前默认分组的实时快照
• 若同时传 expire / multiplier，上游会按更具体的分组筛选

4.2.2 按到期日查询

GET /api/v1/vol-data/query/by-expire?underlying=au2607&expire=20260624

必填参数：

• underlying：标的代码，例如 au2607

建议参数：

• expire：到期日，格式 yyyyMMdd

可选参数：

• multiplier：合约乘数，例如 1000

适用场景：

• 已明确目标到期日，希望获取该到期日下的实时快照

4.2.3 按乘数查询

GET /api/v1/vol-data/query/by-multiplier?underlying=au2607&expire=20260624&multiplier=1000

必填参数：

• underlying：标的代码，例如 au2607

建议参数：

• expire：到期日，格式 yyyyMMdd
• multiplier：合约乘数，例如 1000

适用场景：

• 已明确完整分组，想精确锁定某一条可交易链

4.2.4 历史小时快照查询

GET /api/v1/vol-data/snapshot/by-underlying?underlying=au2607&snapshotTime=1781062200000

用途：

• 查询本地数据库中某个小时档位的历史 T 型快照
• 返回结构与实时快照 GET /api/v1/vol-data/query/by-multiplier 基本一致
• 适合回看某个历史时点的 atm_iv、iv_skew、PCR、标的报价、期权链、Greeks 和盘口隐波

必填参数：

• underlying：标的代码，例如 au2607
• snapshotTime：目标时间戳，毫秒；也可传 last，表示查询当前分组在数据库中最新的一条快照，主要用于非开盘时段获取上次收盘时的快照

可选参数：

• expire：到期日，格式 yyyyMMdd
• multiplier：合约乘数，例如 1000

参数规则：

• 当未传 expire 时，默认选择该 underlying 的最近月
• 当未传 multiplier 时，默认选择该月下最小乘数
• snapshotTime 传毫秒时间戳时会先向下取整到整点，再查询对应小时快照
• snapshotTime=last 时不做时间取整，直接按当前分组查询数据库中 snapshot_hour_ms 最大的一条记录；主要使用场景是在非开盘时段获取上次收盘时的快照

示例：

curl -sS 'https://api.hitick.top/api/v1/vol-data/snapshot/by-underlying?underlying=au2607&snapshotTime=1781062200000' \
  -H 'X-API-Token: your_token_value'

返回核心结构：

{
  "found": true,
  "query_type": "snapshot_by_underlying",
  "underlying": "au2607",
  "expire_date": "20260624",
  "multiplier": 1000,
  "atm_iv": 0.1852,
  "iv_skew": -0.0174,
  "oi_pcr": 1.2389,
  "volume_pcr": 0.8123,
  "data_time_ms": 1781062200000,
  "underlying_quote": {
    "symbol": "au2607",
    "last_price": 812.34
  },
  "rows": [
    {
      "strike": 800,
      "call": {
        "symbol": "au2607-C-800",
        "delta": 0.54,
        "gamma": 0.0012,
        "vega": 0.0831,
        "theta": -0.0245,
        "theo_vol": 0.1841,
        "implied_vol": 0.1863
      },
      "put": {
        "symbol": "au2607-P-800",
        "delta": -0.46,
        "gamma": 0.0011,
        "vega": 0.0818,
        "theta": -0.0229,
        "theo_vol": 0.1874,
        "implied_vol": 0.1889
      }
    }
  ]
}

字段说明：

• found：是否命中该历史快照
• query_type：固定为 snapshot_by_underlying
• underlying：标的代码
• expire_date：实际命中的到期日，格式 yyyyMMdd
• multiplier：实际命中的合约乘数
• atm_iv：该小时快照的 ATM 隐含波动率，小数表示
• iv_skew：该小时快照的隐含波动率偏度
• oi_pcr：按 put.open_interest / call.open_interest 聚合得到的持仓量 PCR
• volume_pcr：按 put.volume / call.volume 聚合得到的成交量 PCR
• data_time_ms：快照所属整点时间，毫秒
• underlying_quote.last_price：该时点标的最新价
• rows[]：该时点期权链，结构与实时 query/* 返回一致

说明：

• 如果 found = false，表示该分组在对应整点没有可用历史快照
• rows[].call / rows[].put 下的 Greeks、理论隐波、盘口隐波字段与实时接口一致
• PCR 口径与实时快照一致：
• oi_pcr = sum(put.open_interest) / sum(call.open_interest)
• volume_pcr = sum(put.volume) / sum(call.volume)
• 缺失 open_interest 或 volume 按 0 处理
• 当 call 侧分母为 0 时，返回 NaN
• atm_iv、theo_vol、implied_vol 等隐波字段均为小数，不是百分比

4.3 时间序列接口

时间序列接口用于查询某个时间区间内的 ATM 隐波、隐含波动率偏度和标的价格时序。

三个 /ts/* 接口统一限制单次查询跨度最多 24 小时（86400000 毫秒）：

• start、end 必填。正数为绝对 Unix 毫秒时间戳；非正数为相对该分组最新有效数据时间的毫秒偏移，0 表示最新数据，并非服务器当前时间。
• 绝对、相对及混合写法均按解析后的时间校验：0 <= end - start <= 86400000。恰好 24 小时允许，超过 24 小时直接报错，不自动截断。
• start=-86400000&end=0 查询最新 24 小时；原相对查询自动裁剪到 12 小时的行为已取消。
• 超限请求不扣查询费用。沿用业务错误格式：HTTP 状态码为 200，客户端必须检查 code，并展示 message。请缩小时间范围后再请求，不要原样重试。

超限返回示例：

{
  "code": 1001,
  "message": "时序查询时间范围不能超过 24 小时（86400000 毫秒），请缩小 start/end 时间范围后重试。",
  "data": null
}

返回重点：

• timestamp_ms
• underlying_last_price
• atm_iv
• iv_skew

4.3.1 按标的查询时序

GET /api/v1/vol-data/ts/by-underlying?underlying=au2607&start=1781062200000&end=1781062300000

必填参数：

• underlying：标的代码，例如 au2607
• start：起始时间戳，毫秒
• end：结束时间戳，毫秒

可选参数：

• expire：到期日，格式 yyyyMMdd
• multiplier：合约乘数，例如 1000

4.3.2 按到期日查询时序

GET /api/v1/vol-data/ts/by-expire?underlying=au2607&expire=20260624&start=1781062200000&end=1781062300000

必填参数：

• underlying：标的代码，例如 au2607
• start：起始时间戳，毫秒
• end：结束时间戳，毫秒

建议参数：

• expire：到期日，格式 yyyyMMdd

可选参数：

• multiplier：合约乘数，例如 1000

4.3.3 按乘数查询时序

GET /api/v1/vol-data/ts/by-multiplier?underlying=au2607&expire=20260624&multiplier=1000&start=1781062200000&end=1781062300000

必填参数：

• underlying：标的代码，例如 au2607
• start：起始时间戳，毫秒
• end：结束时间戳，毫秒

建议参数：

• expire：到期日，格式 yyyyMMdd
• multiplier：合约乘数，例如 1000

4.4 GEX 曲线接口

GEX 接口用于查询 Gamma Exposure 扫描结果，适合分析：

• 当前净 GEX 是正还是负
• 价格上移 / 下移后净 GEX 如何变化
• 零 gamma 位置在哪里
• 当前价附近是否存在 GEX 翻转区

4.4.1 按标的查询 GEX

GET /api/v1/vol-data/gex/by-underlying?underlying=au2607

必填参数：

• underlying：标的代码，例如 au2607

可选参数：

• expire：到期日，格式 yyyyMMdd
• multiplier：合约乘数，例如 1000

4.4.2 按到期日查询 GEX

GET /api/v1/vol-data/gex/by-expire?underlying=au2607&expire=20260624

必填参数：

• underlying：标的代码，例如 au2607

建议参数：

• expire：到期日，格式 yyyyMMdd

可选参数：

• multiplier：合约乘数，例如 1000

4.4.3 按乘数查询 GEX

GET /api/v1/vol-data/gex/by-multiplier?underlying=au2607&expire=20260624&multiplier=1000

必填参数：

• underlying：标的代码，例如 au2607

建议参数：

• expire：到期日，格式 yyyyMMdd
• multiplier：合约乘数，例如 1000

4.5 GEX 历史小时快照接口

GEX 历史小时快照接口用于查询本地数据库中已落库的整点 GEX 结构。它适合回看某一小时档位的净 GEX、零 gamma 和扫描曲线，而不是重新按当前行情计算。

GET /api/v1/vol-data/gex/snapshot/by-underlying?underlying=au2607&snapshotTime=1781651875123

用途：

• 查询本地数据库中某个小时档位的历史 GEX 快照
• 返回结构与实时 GEX GET /api/v1/vol-data/gex/by-multiplier 基本一致
• 适合回看某个历史时点的 current_gex、zero_gamma、spot_price 和 points

必填参数：

• underlying：标的代码，例如 au2607
• snapshotTime：目标时间戳，毫秒；也可传 last，表示查询当前分组在数据库中最新的一条 GEX 快照，主要用于非开盘时段获取上次收盘时的 GEX 快照

可选参数：

• expire：到期日，格式 yyyyMMdd
• multiplier：合约乘数，例如 1000

参数规则：

• 当未传 expire 时，默认选择该 underlying 的最近月
• 当未传 multiplier 时，默认选择该月下最小乘数
• snapshotTime 传毫秒时间戳时会先向下取整到整点，再查询对应小时快照
• snapshotTime=last 时不做时间取整，直接按当前分组查询数据库中 snapshot_hour_ms 最大的一条记录；主要使用场景是在非开盘时段获取上次收盘时的 GEX 快照
• 计费 payload 中会同时记录实际查询的 snapshotTime 和原始请求的 requestedSnapshotTime

示例：

curl -sS 'https://api.hitick.top/api/v1/vol-data/gex/snapshot/by-underlying?underlying=au2607&snapshotTime=1781651875123' \
  -H 'X-API-Token: your_token_value'

返回核心结构：

{
  "found": true,
  "query_type": "gex_by_multiplier",
  "underlying": "au2607",
  "expire_date": "20260624",
  "multiplier": "1000",
  "data_time_ms": 1781650800123,
  "spot_price": 919.12,
  "price_min": 827.208,
  "price_max": 1011.032,
  "range_pct": 0.1,
  "steps": 81,
  "current_gex": -1582342.118,
  "zero_gamma": 941.47,
  "points": [
    {
      "price": 827.208,
      "net_gex": -2120341.441
    }
  ],
  "error": null
}

字段说明：

• found：是否命中该历史 GEX 快照
• query_type：命中快照时通常保留落库时的实时查询类型，例如 gex_by_multiplier；未命中时为 gex_snapshot_by_underlying
• underlying：标的代码
• expire_date：实际命中的到期日，格式 yyyyMMdd
• multiplier：实际命中的合约乘数
• data_time_ms：落库快照对应的上游行情时间戳
• spot_price：该快照用于计算 GEX 的标的价格
• current_gex：该快照现价下的净 GEX
• zero_gamma：若曲线穿越 0，则返回线性插值得到的零 gamma 价格，否则为 null
• points[]：扫描价格点数组，结构与实时 gex/* 返回一致

说明：

• 如果 found = false，表示该分组在对应整点没有可用 GEX 快照
• 后台定时任务按可用分组抓取实时 gex/by-multiplier，并以整点小时作为 snapshotHourMs 落库
• 只有上游返回 found = true 且 data_time_ms 距当前时间不超过 30 分钟时，后台才会持久化该小时 GEX 快照

4.6 GEX 图片接口

GEX 图片接口用于获取已渲染的 GEX 结构图 CDN 地址，适合聊天机器人、外部系统或移动端直接展示图片。默认生成实时 GEX 图；传入 snapshotTime 后可生成过去某个小时档位的历史 GEX 图，传 snapshotTime=last 可生成当前分组数据库最新快照图，主要用于非开盘时段获取上次收盘时的 GEX 图。

GET /api/v1/vol-data/gex-image/by-underlying?underlying=au2607

必填参数：

• underlying：标的代码，例如 au2607

建议参数：

• expire：到期日，格式 yyyyMMdd
• multiplier：合约乘数，例如 1000
• snapshotTime：目标时间戳，毫秒；也可传 last，表示使用当前分组数据库最新 GEX 快照生成图片，主要用于非开盘时段获取上次收盘时的 GEX 图

返回示例：

{
  "code": 0,
  "message": "ok",
  "data": {
    "url": "https://cdn.example.com/gex/au2607-20260624-1000.png",
    "generated_at": 1781650800000
  }
}

调用说明：

• 只传 underlying 即可获取该标的的 GEX 图片 URL
• expire / multiplier 可选；未传时系统会自动选择可用组合
• 未传 snapshotTime 时生成实时 GEX 图；传毫秒时间戳时生成对应小时快照图；传 last 时生成最新落库快照图，主要用于非开盘时段获取上次收盘时的 GEX 图
• 返回的 url 可直接用于图片展示或发送
• 成功返回图片 URL 后触发计费；失败时接口返回错误信息

5. 参数说明总表

所有接口的 query 参数都来自下面这组字段：

参数名	类型	是否必填	适用接口	说明
underlying	string	query/*、snapshot/*、ts/*、gex/*、gex-image/* 必填	query/*、snapshot/*、ts/*、gex/*、gex-image/*	标的代码，例如 au2607、cu2607
expire	string	视场景建议传	query/*、snapshot/*、ts/*、gex/*、gex-image/*	到期日，格式 yyyyMMdd，例如 20260624
multiplier	string / number	视场景建议传	query/*、snapshot/*、ts/*、gex/*、gex-image/*	合约乘数，例如 1000、5
start	string / number	ts/* 必填	ts/*	起始毫秒时间戳
end	string / number	ts/* 必填	ts/*	结束毫秒时间戳
snapshotTime	string / number	snapshot/*、gex/snapshot/* 必填；gex-image/* 可选	snapshot/*、gex/snapshot/*、gex-image/*	目标毫秒时间戳，服务端会向下取整到整点查询；也可传 last 查询当前分组数据库最新快照，主要用于非开盘时段获取上次收盘时的快照。用于 gex-image/* 时，表示生成历史 GEX 图或最新落库 GEX 图

实务建议：

• 如果你只知道标的代码，先用 by-underlying
• 如果你在做单一期限分析，优先传 expire
• 如果同一标的存在多个乘数，建议显式传 multiplier
• 时间区间建议用毫秒级 Unix 时间戳，避免时区歧义

6. 返回结构详解

6.1 快照查询返回结构

三个 query/* 接口的 data 顶层结构一致：

{
  "found": true,
  "query_type": "by_underlying",
  "underlying": "au2607",
  "expire_date": "20260624",
  "multiplier": 1000,
  "atm_iv": 0.29434965770081106,
  "iv_skew": -0.0174,
  "oi_pcr": 1.2389,
  "volume_pcr": 0.8123,
  "data_time_ms": 1781071070500,
  "api_latency_ms": 132,
  "calc_latency_ms": 8,
  "underlying_quote": {
    "symbol": "au2607",
    "last_price": 919.12,
    "bid_price": 918.94,
    "ask_price": 919.24,
    "open_price": 930.0,
    "highest_price": 951.2,
    "lowest_price": 912.6,
    "pre_settlement_price": 947.94
  },
  "rows": [
    {
      "strike": 704.0,
      "call": {
        "symbol": "au2607C704",
        "delta": 0.9920005958397674,
        "gamma": 0.00019125757057879587,
        "vega": 0.03419517453622726,
        "theta": -0.10879514980386451,
        "theo_vol": 0.584031857797719,
        "implied_vol": null,
        "implied_bid_vol": null,
        "implied_ask_vol": null,
        "short_margin": 364215.4
      },
      "put": {
        "symbol": "au2607P704",
        "delta": -0.007040959652272832,
        "gamma": 0.00019125757057879587,
        "vega": 0.03419517453622726,
        "theta": -0.10879514980386451,
        "theo_vol": 0.584031857797719,
        "implied_vol": null,
        "implied_bid_vol": null,
        "implied_ask_vol": null,
        "short_margin": 85297.7
      }
    }
  ],
  "error": null
}

6.1.1 顶层字段

• found：是否命中数据
• query_type：查询类型，如 by_underlying、by_expire、by_multiplier
• underlying：标的代码
• expire_date：到期日
• multiplier：合约乘数
• atm_iv：当前 ATM 隐含波动率，使用小数表示，不是百分比
• iv_skew：当前隐含波动率偏度
• oi_pcr：按 put.open_interest / call.open_interest 聚合得到的持仓量 PCR
• volume_pcr：按 put.volume / call.volume 聚合得到的成交量 PCR
• data_time_ms：快照数据时间戳，毫秒
• api_latency_ms：上游接口耗时，毫秒
• calc_latency_ms：上游计算耗时，毫秒
• error：上游错误对象；正常时通常为 null

6.1.2 标的报价字段

underlying_quote 用于表示标的实时行情，稳定字段包括：

• underlying_quote.symbol：标的代码
• underlying_quote.last_price：标的最新价
• underlying_quote.bid_price / ask_price：买一价和卖一价
• underlying_quote.open_price：Basic Data 返回的当前交易日开盘价
• underlying_quote.highest_price：Basic Data 返回的当前交易日最高价
• underlying_quote.lowest_price：Basic Data 返回的当前交易日最低价
• underlying_quote.pre_settlement_price：昨结算价
• underlying_quote.open_interest：持仓量
• underlying_quote.volume：成交量
• underlying_quote.exchange：交易所
• underlying_quote.timestamp_ms：行情源时间戳

说明：

• 开盘、最高和最低均直接透传 Basic Data，不由 volData 的分钟序列推算。
• 字段在上游尚未形成有效价格时可能为 null。

6.1.3 期权链字段

rows 表示按行权价展开的期权链。

• rows[].strike：行权价
• rows[].call：该行权价对应的看涨期权数据
• rows[].put：该行权价对应的看跌期权数据

如果某一侧无数据，对应 call 或 put 可能为空。

6.1.4 报价相关字段

当前快照结构中，文档已确认或约定可重点关注以下报价相关字段：

• underlying_quote.last_price：标的最新价
• underlying_quote.open_price / highest_price / lowest_price：当前交易日开高低
• underlying_quote.pre_settlement_price：昨结算价
• rows[].strike：行权价
• rows[].call.symbol / rows[].put.symbol：期权合约代码

如果上游后续补充盘口价、买一卖一、成交量、持仓量等字段，也会继续透传在 call / put 节点中。当前这份对外文档先只写明已验证存在的稳定字段。

6.1.5 隐含波动率字段

本接口可提供多层次的隐波数据：

• atm_iv：整个分组当前的 ATM 隐含波动率
• iv_skew：整个分组当前的隐含波动率偏度
• rows[].call.theo_vol / rows[].put.theo_vol：模型理论波动率
• rows[].call.implied_vol / rows[].put.implied_vol：该合约的中间隐含波动率
• rows[].call.implied_bid_vol / rows[].put.implied_bid_vol：按买价反推的隐含波动率
• rows[].call.implied_ask_vol / rows[].put.implied_ask_vol：按卖价反推的隐含波动率

字段解释：

• atm_iv：最适合做品种层面的升波 / 降波、时点比较、排序分析
• theo_vol：更偏模型内部估计值，适合与市场隐波对比
• implied_vol：更适合看单个合约当前的市场定价隐波
• implied_bid_vol / implied_ask_vol：适合衡量盘口两侧隐波差异和流动性状态

注意：

• 所有隐波字段都以小数表示，例如 0.28 表示 28%
• 返回 null 表示该时刻无法稳定反推出对应隐波，不应直接当作 0

6.1.6 PCR 字段

当前快照顶层还会返回两个 PCR 指标：

• oi_pcr：持仓量 Put/Call Ratio
• volume_pcr：成交量 Put/Call Ratio

PCR 口径：

• oi_pcr = sum(put.open_interest) / sum(call.open_interest)
• volume_pcr = sum(put.volume) / sum(call.volume)
• 缺失 open_interest 或 volume 按 0 处理
• 当 call 侧分母为 0 时，返回 NaN

6.1.7 Greeks 字段

本接口目前明确可返回以下 Greeks：

• delta
• gamma
• vega
• theta

字段位置：

• rows[].call.delta
• rows[].call.gamma
• rows[].call.vega
• rows[].call.theta
• rows[].put.delta
• rows[].put.gamma
• rows[].put.vega
• rows[].put.theta

含义说明：

• delta：标的价格变化 1 单位时，期权价格的一阶敏感度
• gamma：delta 对标的价格变化的二阶敏感度
• vega：期权价格对隐含波动率变化的敏感度
• theta：期权价格对时间流逝的敏感度

使用建议：

• 做方向判断时优先看 delta
• 做 Gamma 风险或 Gamma 暴露分析时看 gamma
• 做升波 / 降波敏感度分析时看 vega
• 做临近到期的时间损耗分析时看 theta

6.1.7 保证金字段

• rows[].call.short_margin
• rows[].put.short_margin

说明：

• short_margin 面向卖方场景，表示卖出该期权时的参考保证金金额
• 可用于估算资金占用、静态收益率和风控承受能力
• 该字段是参考值，实际交易保证金仍可能因期货公司、交易所规则、账户风险参数和盘中行情而变化

6.2 时间序列返回结构

三个 ts/* 接口的 data 顶层结构一致：

{
  "found": true,
  "query_type": "ts_by_underlying",
  "underlying": "au2607",
  "expire_date": "20260624",
  "multiplier": 1000,
  "start_ms": 1781062200000,
  "end_ms": 1781062300000,
  "rows": [
    {
      "timestamp_ms": 1781062200500,
      "underlying_last_price": 911.92,
      "atm_iv": 0.3072331463176879,
      "iv_skew": -0.0174
    }
  ],
  "error": null
}

字段说明：

• found：是否命中
• query_type：查询类型，可能为 ts_by_underlying、ts_by_expire、ts_by_multiplier
• underlying：标的代码
• expire_date：到期日
• multiplier：合约乘数
• start_ms：请求起始时间戳
• end_ms：请求结束时间戳
• rows：时间序列点数组
• rows[].timestamp_ms：数据点时间戳，毫秒
• rows[].underlying_last_price：该时点的标的最新价
• rows[].atm_iv：该时点的 ATM 隐含波动率
• rows[].iv_skew：该时点的隐含波动率偏度
• error：上游错误对象；正常时通常为 null

时序能力总结：

• 可以做日内升波 / 降波分析
• 可以做开盘到当前的 atm_iv 变化分析
• 可以做某一交易时段的标的价格与隐波联动分析
• 可以作为主观信号、量化特征、图表展示的原始输入

6.3 GEX 曲线返回结构

三个 gex/* 接口的 data 顶层结构一致：

{
  "found": true,
  "query_type": "gex_by_underlying",
  "underlying": "au2607",
  "expire_date": "20260624",
  "multiplier": 1000,
  "data_time_ms": 1781071070500,
  "spot_price": 919.12,
  "price_min": 827.208,
  "price_max": 1011.032,
  "range_pct": 0.1,
  "steps": 81,
  "current_gex": -1582342.118,
  "zero_gamma": 941.47,
  "points": [
    {
      "price": 827.208,
      "net_gex": -2120341.441
    }
  ],
  "error": null
}

字段说明：

• found：是否命中
• query_type：查询类型，可能为 gex_by_underlying、gex_by_expire、gex_by_multiplier
• underlying：标的代码
• expire_date：到期日
• multiplier：合约乘数
• data_time_ms：快照时间戳
• spot_price：当前标的价格，GEX 扫描中心
• price_min：扫描下界
• price_max：扫描上界
• range_pct：扫描半区间比例，例如 0.1 表示以现价上下各 10% 扫描
• steps：扫描网格数量
• current_gex：当前现价下的净 GEX
• zero_gamma：若曲线穿越 0，则返回线性插值得到的零 gamma 价格，否则为 null
• points：扫描价格点数组
• points[].price：扫描价格点
• points[].net_gex：该价格点对应的净 GEX
• error：上游错误对象；正常时通常为 null

GEX 能力总结：

• 可看当前市场整体是正 GEX 还是负 GEX
• 可判断现价附近是否接近零 gamma 区域
• 可辅助分析价格波动放大 / 收敛的潜在结构
• 可与 gamma、open interest、持仓结构分析配合使用

6.4 GEX 历史小时快照返回结构

gex/snapshot/by-underlying 返回本地落库的小时 GEX 快照。命中时结构与实时 gex/* 基本一致，未命中时返回一个轻量的未命中对象：

{
  "found": false,
  "query_type": "gex_snapshot_by_underlying",
  "underlying": "au2607",
  "expire_date": "20260624",
  "multiplier": "1000"
}

使用建议：

• 需要“某个整点附近的 GEX 结构”时使用 gex/snapshot/by-underlying
• 需要“当前实时 GEX 结构”时使用 gex/by-underlying、gex/by-expire 或 gex/by-multiplier
• snapshotTime 可传任意毫秒时间戳，服务端会按整点小时归档查询；也可传 last 查询当前分组数据库最新快照，主要用于非开盘时段获取上次收盘时的快照

7. 波动率日差说明

如果需要回答这类问题：

• “今天 xx 有升波吗？”
• “今天升波最大的品种是什么？”
• “今天哪些品种降波最多？”

建议统一使用“波动率日差”口径。

定义：

• 波动率日差 = 当前波动率 - 上一交易日收盘时波动率
• 波动率上升 / 下降，均以上一交易日收盘时的波动率为比较基准

使用建议：

1. 先用快照接口读取当前 atm_iv
2. 再用时间序列接口读取覆盖“上一交易日收盘前后”和“当前时刻”的数据
3. 取上一交易日收盘时最近的 atm_iv 作为对比基准
4. 用当前 atm_iv - 上一交易日收盘时 atm_iv 得到波动率日差

判读规则：

• 波动率日差 > 0：表示今天升波
• 波动率日差 < 0：表示今天降波
• 波动率日差 = 0：表示与上一交易日收盘相比基本持平

注意：

• atm_iv 为小数形式返回，例如 0.28 表示 28%
• 做跨品种比较时，建议统一使用同一时点的当前快照，并统一以上一交易日收盘时为基准
• 如果上一交易日收盘附近没有有效时序点，应选择最接近收盘时间的可用点，并在结果中说明是“收盘附近参考值”

8. Agent 接入规范

如果给 Agent 使用，建议按下面的最小规则封装。

8.1 工具名建议

orange_resolve_subject
orange_vol_data

orange_resolve_subject 输入 query，可选 limit 默认 5、最大 5。它返回推荐的 selected 三元组及最多 5 个候选，不返回完整目录、行情或期权链。

8.2 输入结构建议

{
  "action": "by_underlying | snapshot_by_underlying | gex_snapshot_by_underlying | ts_by_underlying | ts_by_expire | ts_by_multiplier | gex_by_underlying | gex_by_expire | gex_by_multiplier | gex_image_by_underlying",
  "params": {
    "underlying": "au2607",
    "expire": "20260624",
    "multiplier": "1000",
    "start": "1781062200000",
    "end": "1781062300000",
    "fullChain": false
  }
}

参数要求：

• action = by_underlying：必须传 underlying；expire、multiplier 可选，未传时自动选择最早到期日及该到期日最小乘数；默认只返回现价上下 10% 行权价档位，完整链需传 fullChain=true
• action = snapshot_by_underlying：必须传 underlying、snapshotTime，建议传 expire、multiplier；snapshotTime 可为毫秒时间戳或 last，其中 last 主要用于非开盘时段获取上次收盘时的快照
• action = gex_snapshot_by_underlying：必须传 underlying、snapshotTime，建议传 expire、multiplier；snapshotTime 可为毫秒时间戳或 last，其中 last 主要用于非开盘时段获取上次收盘时的 GEX 快照
• action = ts_by_underlying：必须传 underlying、start、end
• action = ts_by_expire：必须传 underlying、start、end，建议传 expire
• action = ts_by_multiplier：必须传 underlying、start、end，建议传 expire、multiplier
• action = gex_by_underlying：必须传 underlying
• action = gex_by_expire：必须传 underlying，建议传 expire
• action = gex_by_multiplier：必须传 underlying，建议传 expire、multiplier
• action = gex_image_by_underlying：必须传 underlying，建议传 expire、multiplier；未传时后端自动补齐；可选传 snapshotTime 毫秒时间戳或 last 生成历史 GEX 图，其中 last 主要用于非开盘时段获取上次收盘时的 GEX 图

8.3 路由映射

• by_underlying -> GET /api/v1/vol-data/query/by-underlying
• snapshot_by_underlying -> GET /api/v1/vol-data/snapshot/by-underlying
• gex_snapshot_by_underlying -> GET /api/v1/vol-data/gex/snapshot/by-underlying
• ts_by_underlying -> GET /api/v1/vol-data/ts/by-underlying
• ts_by_expire -> GET /api/v1/vol-data/ts/by-expire
• ts_by_multiplier -> GET /api/v1/vol-data/ts/by-multiplier
• gex_by_underlying -> GET /api/v1/vol-data/gex/by-underlying
• gex_by_expire -> GET /api/v1/vol-data/gex/by-expire
• gex_by_multiplier -> GET /api/v1/vol-data/gex/by-multiplier
• gex_image_by_underlying -> GET /api/v1/vol-data/gex-image/by-underlying

8.4 Agent 调用流程建议

1. 从安全存储读取 X-API-Token
2. 标的不完整时先调用 orange_resolve_subject；命中且无歧义后使用 selected，否则向用户澄清
3. 根据目标调用 orange_vol_data
4. 检查平台响应 code
5. MCP by_underlying 默认只返回现价上下 10% 档位；根据 chain_meta 判断是否发生裁剪或缺少现价回退
6. 如果确实需要完整期权链，显式传 params.fullChain=true
7. 如果需要分析一段时间内的隐波变化，读取 ts/* 的 rows
8. 如果需要分析 Gamma Exposure 分布，读取 gex/* 的 points、current_gex、zero_gamma
9. 如果需要回看历史整点 GEX 结构，调用 gex_snapshot_by_underlying，读取 points、current_gex、zero_gamma
10. 如果因为未开盘、行情源不可用或实时接口返回 found=false 导致实时 query/* 或 gex/* 获取失败，可以改用 snapshot/by-underlying 或 gex/snapshot/by-underlying，并传 snapshotTime=last；这是 last 的主要使用场景，返回的是当前分组数据库最新快照，通常可视为上次收盘时的快照
11. 当用户询问特定标的的 GEX、零 gamma、正负 GEX 或 GEX 结构时，除 gex/* 结构化数据外，可以额外调用 gex_image_by_underlying，把图片 URL 一并返回，方便用户理解与查看
12. 如果需要给用户直接展示或发送 GEX 图，调用 gex_image_by_underlying 并使用返回的 url；如果用户需要过去的 GEX 图，传 snapshotTime 毫秒时间戳，若处于非开盘时段、需要上次收盘图则传 snapshotTime=last

8.5 Agent 错误处理建议

• 平台 code != 0：直接抛出平台错误
• 401/403：扣费侧使用 Authorization: Bearer <X-API-Token> 调用计费接口时鉴权失败
• 扣费失败：直接透传平台错误，提示用户检查 token 或计费服务状态
• 404 且 found = false：按“未命中”处理，不要当系统故障
• 上游超时或异常：建议重试，并保留原始错误信息

9. 计费与明细说明

• 平台在业务数据成功返回后，使用 OpenAI 兼容 POST /chat/completions 发起同步扣费
• groups 不触发扣费
• query/*、snapshot/*、ts/*、gex/*、gex-image/* 成功返回后触发扣费
• 对外业务接口协议保持不变，仍然由调用方传 X-API-Token
• model 固定为 VolData，用于标识业务类型
• messages 保持最简，只携带本次请求路径和参数
• 扣费请求头格式固定为 Authorization: Bearer <X-API-Token>
• 外部计费接口返回 HTTP 200 视为扣费成功
• 扣费失败时，业务响应直接返回错误，不再写本地 usage 明细或异步扣费任务

10. 最小测试示例

查询实时快照：

curl -sS 'https://api.hitick.top/api/v1/vol-data/query/by-underlying?underlying=au2607' \
  -H 'X-API-Token: your_token_value'

查询 ATM IV 时序：

curl -sS 'https://api.hitick.top/api/v1/vol-data/ts/by-underlying?underlying=au2607&start=1781062200000&end=1781062300000' \
  -H 'X-API-Token: your_token_value'

查询 GEX 曲线：

curl -sS 'https://api.hitick.top/api/v1/vol-data/gex/by-underlying?underlying=au2607' \
  -H 'X-API-Token: your_token_value'

11. 接入建议

• 手动接入适合后端服务、脚本、联调测试
• Agent 接入适合自动查询、波动率分析、Greeks 辅助处理、GEX 结构分析
• 建议给不同用途创建不同 Token，方便审计和隔离