Option Volatility

GET /api/v1.0/quote/{symbol}/option-volatility

Get implied volatility (IV), historical volatility (HV), volatility premium analysis and text analysis for an option contract.

Parameters

Name	Type	In	Required	Description
symbol	string	path	yes	Option contract code (must be an option contract, not an underlying stock code), e.g. HK.TCH260629C470000.
query_time_period	int	query	no	Query time period, default 2. 1=1 week, 2=1 month, 3=3 months, 4=6 months, 5=1 year. See Naming Dictionary.
hv_time_period	int	query	no	Historical volatility period (calendar days), default 30, range 5~250.

Request Example

curl 'https://webapi.futunn.com/api/v1.0/quote/HK.TCH260528C230000/option-volatility?query_time_period=2&hv_time_period=30' | jq

Response Fields

Returns data.item_list[] (time series) + data.extra (period summary).

data.item_list[] each data point:

Field	Type	Description
timestamp	int64	Data time (millisecond timestamp).
implied_volatility	float	Implied volatility (percentage, e.g. 28.391 means 28.391%).
history_volatility	float	Historical volatility (percentage).
volatility_premium	float	Volatility premium (IV - HV, percentage).

data.extra period summary:

Field	Type	Description
average_impvol	float	Period average implied volatility (percentage).
impvol_status	string	Volatility analysis status: FLUCTUATING / OVERVALUED / UNDERVALUED.
analysis	string	Volatility analysis text, multi-line separated by \n.

Supported Markets

• Supported markets: HK / US / JP equity options + HK / US index options.
• Only option contract codes are accepted as input; passing an underlying stock code returns invalid_parameter.
• Time series length is limited by query_time_period.

Error Codes

ret_code	error.code	Trigger Scenario	Suggested Handling
0	—	Success	—
-3	invalid_parameter	Passed underlying stock code instead of option contract / query_time_period not in 1-5 / hv_time_period not in 5-250	Correct request and retry; symbol must be an option contract code
-7	invalid_symbol	symbol format invalid or backend cannot recognize this contract	Verify contract code validity via option chain API
-10	no_data	Backend has no volatility data (contract suspended / insufficient data / IV price is 0)	Try different contract / different query_time_period and retry
-4	internal_error	Backend internal error	Retry; if persistent, contact backend team

Response Example

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