期权波动率

GET /v1/quote/{symbol}/option-volatility

获取期权合约的隐含波动率（IV）与历史波动率（HV）分析序列。

请求参数

参数	类型	位置	必填	说明
symbol	string	路径	是	期权合约代码（必须是期权合约，不能传正股代码），例 HK.TCH260629C470000。
query_time_period	int	查询	否	查询时间周期，默认 2。1=1 周, 2=1 月, 3=3 月, 4=6 月, 5=1 年。详见命名词典。
hv_time_period	int	查询	否	历史波动率周期（自然日），默认 30，范围 5~250。

请求示例

curl '$ip/v1/quote/HK.TCH260629C470000/option-volatility' | jq
curl '$ip/v1/quote/HK.TCH260629C470000/option-volatility?query_time_period=3&hv_time_period=60' | jq

响应字段

返回 data.item_list[]（时间序列）+ data.extra（区间汇总）。

data.item_list[] 每个数据点：

字段	类型	说明
timestamp	int64	数据时间（毫秒时间戳）。
implied_volatility	float	隐含波动率（百分数，如 28.391 表示 28.391%）。
history_volatility	float	历史波动率（百分数）。
volatility_premium	float	波动率溢价（IV - HV，百分数）。

data.extra 区间汇总：

字段	类型	说明
average_impvol	float	区间平均隐含波动率（百分数）。
impvol_status	string	波动率分析状态：FLUCTUATING（震荡中）/ OVERVALUED（高估）/ UNDERVALUED（低估）。
analysis	string	波动率分析文案，多行用 \n 分隔。

限制范围

• 支持市场：HK / US / JP 正股期权 + HK / US 指数期权。
• 仅支持期权合约代码作为入参；传入正股代码会返回 invalid_parameter。
• 时间序列长度受 query_time_period 限制。

错误码

ret_code	error.code	触发条件	处理建议
0	—	成功	—
-3	invalid_parameter	传正股代码而非期权合约 / query_time_period 不在 1-5 / hv_time_period 不在 5-250	校正请求后重试；symbol 必须传期权合约代码
-7	invalid_symbol	symbol 格式不合法或后端无法识别该合约	通过期权链接口确认合约代码合法性
-10	no_data	后端无可用波动率数据（合约停牌 / 数据不足 / IV 价格为 0）	换合约 / 换 query_time_period 后重试
-4	internal_error	后端内部错误	重试；持续失败请联系后端

响应示例

{
  "ret_code": 0,
  "data": {
    "item_list": [
      {
        "timestamp": 1777910400000,
        "implied_volatility": 28.391,
        "history_volatility": 32.105,
        "volatility_premium": -3.714
      }
    ],
    "extra": {
      "average_impvol": 28.389,
      "impvol_status": "FLUCTUATING",
      "analysis": "For 90.00% of the time in the recent 1 month, the IV is greater than the HV..."
    }
  }
}