期權波動率

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.TCH260528C230000/option-volatility?query_time_period=2&hv_time_period=30' | 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..."
    }
  }
}