IV Surface

What is this endpoint for?

The IV surface endpoint lets you calculate volatility from options market prices. Feed the endpoint a set of maturity dates or timeframes for when options can be exercised, and you'll receive a volatility surface, which shows how volatility changes over different dates and prices.

You can get volatility estimates based on:

A specific set of strike prices
A forward-log-moneyness grid
A specific set of delta values
A delta grid

The calculation methodology leverages space and time interpolation.

Currently supported assets and exchanges:

BTC, ETH, SOL, MATIC, XRP on Deribit.
BTC, ETH on OKX.
BTC, ETH on Deribit & OKX (aggregated).

If you need data from other exchanges, we can add them on request.

Endpoint

https://us.market-api.kaiko.io/v2/data/analytics.v2/implied_volatility_surface

Parameters

Short listed-maturities (e.g. 7 days time-to-maturity) are only available for individual exchange.
Time extrapolation is not permitted. I.e. the shortest requested expiry should be after the exchange’s shortest expiry, and the furthest requested expiry must be before the exchange’s latest expiry. If these conditions are not met, only a partial surface will be returned within the available expiry range. The completeness of the output is indicated in the complete_output field.
Strikes and forward-log-moneynesses are only available when retrieving implied volatilities by strikes or forward-log-moneynesses (not by delta).

Parameter Required Description Example

Parameter	Required	Description	Example
`base`	Yes	The desired base as the underlying of the options. See asset support above.	`btc`, `eth`
`quote`	Yes	The desired quote as the underlying of the options. See asset support above.	`usd`
`exchanges`	Yes	The desired exchange as source of options data. See exchange support above.	`drbt`
`value_time`	Yes	The time at which to compute implied volatilities The time t should be smaller than the lowest requested expiry.	`2022-06-25T16:00:00.000Z`
`expiry_list`	Yes, if the set of parameters (`tte_min`, `tte_max`, `tte_step`) is not used.	The expiries for which the implied volatilities are to be computed. Expiries can be listed or non-listed ones. Expiries should be between minimum and maximum listed maturities on exchange. If not, a partial output will be returned. Either `expiry_list` or (`tte_min`, `tte_max`, `tte_step`) should be filled.	`expiry_list=2022-08-28T08:00:00.000Z, 2022-08-30T08:00:00.000Z` or `tte_min=0.034288&tte_max=1&tte_step=0.02`
`tte_min`	Yes, if `expiry_list` is not used. To be used along with `tte_max`, `tte_step`.	Minimum time-to-expiry on the time grid. Strictly positive value allowed. If the `tte_min` is below the time to expiry associated with the minimum listed maturity, partial output will be returned. Either `expiry_list` or (`tte_min`, `tte_max`, `tte_step`) should be filled.	`0.034288`
`tte_max`	Yes, if `expiry_list` is not used. To be used along with `tte_min`, `tte_step`.	Maximum time-to-expiry on the time grid. Strictly positive value above the `tte_min`. If the `tte_max` is above the time to expiry associated with the maximum listed maturity, partial output will be returned. Either `expiry_list` or `(tte_min, tte_max,tte_step)` should be filled.	`1`
`tte_step`	Yes, if `expiry_list` is not used. To be used along with `tte_min`, `tte_max`.	Step between two time-to-expiries in time grid. Strictly positive value allowed. Either `expiry_list` or `(tte_min, tte_max, tte_step)` should be filled.	`0.02`
`strike_list`	Yes, if the set of parameters (`f_log_min`, `f_log_max`, `f_log_step`) or `deltas` or the set of parameters (`delta_min`, `delta_max`, `delta_step`) are not used.	The strike prices for which the implied volatilities are to be computed. Strike prices can be listed or non-listed ones. Strictly positives values allowed. Either `strike_list` , (`f_log_m_min`, `f_log_m_max`, `f_log_m_step`), `deltas` or (`delta_min`, `delta_max`, `delta_step`) should be filled.	`strike_list=25000, 29150, 29155, 29160` or `f_log_m_min=-1.5&f_log_m_max=1.5&f_log_m_step=0.05`
`f_log_m_min`	Yes, if `strike_list` or `deltas` or the set of parameters (`delta_min`, `delta_max`, `delta_step`) are not used. To be used along with `f_log_m_max`, `f_log_m_step`.	Minimum forward log-moneyness on the space grid. Either `strike_list` , (`f_log_m_min`, `f_log_m_max`, `f_log_m_step`), `deltas` or (`delta_min`, `delta_max`, `delta_step`) should be filled.	`-1.5`
`f_log_m_max`	Yes, if `strike_list` or `deltas` or the set of parameters (`delta_min`, `delta_max`, `delta_step`) are not used. To be used along with `f_log_m_min`, `f_log_m_step`.	Maximum forward log-moneyness on the space grid. Either `strike_list` , (`f_log_m_min`, `f_log_m_max`, `f_log_m_step`), `deltas` or (`delta_min`, `delta_max`, `delta_step`) should be filled.	`1`
`f_log_m_step`	Yes, if `strike_list` or `deltas` or the set of parameters (`delta_min`, `delta_max`, `delta_step`) are not used. To be used along with `f_log_m_min`, `f_log_m_max`.	Step between two forward log moneyness in space grid. Either `strike_list` , (`f_log_m_min`, `f_log_m_max`, `f_log_m_step`), `deltas` or (`delta_min`, `delta_max`, `delta_step`) should be filled.	`0.02`
`deltas`	Yes, if `strike_list` or the sets of parameters `(delta_min, delta_max, delta_step)` or (`f_log_m_min`, `f_log_m_max`, `f_log_m_step`) are not used.	The delta levels (of a Call option) for which the implied volatilities are to be computed. Only delta values between `0.01` and `0.99` are allowed. Either `strike_list` , (`f_log_m_min`, `f_log_m_max`, `f_log_m_step`), `deltas` or (`delta_min`, `delta_max`, `delta_step`) should be filled.	`deltas=0.25,0.5,0.75`
`delta_min`	Yes, if `strike_list` or `deltas` or the set of parameters (`f_log_m_min`, `f_log_m_max`, `f_log_m_step`) are not used. To be used along with `delta_max`, `delta_step`.	Minimum delta (of a Call option) on the space grid. Only delta values between `0.01` and `0.99` are allowed. Either `strike_list` , (`f_log_m_min`, `f_log_m_max`, `f_log_m_step`), `deltas` or (`delta_min`, `delta_max`, `delta_step`) should be filled.	`0.01`
`delta_max`	Yes, if `strike_list` or `deltas` or the set of parameters (`f_log_m_min`, `f_log_m_max`, `f_log_m_step`) are not used. To be used along with `delta_min`, `delta_step`.	Maximum delta (of a Call option) on the space grid. Only delta values between `0.01` and `0.99` are allowed. Either `strike_list` , (`f_log_m_min`, `f_log_m_max`, `f_log_m_step`), `deltas` or (`delta_min`, `delta_max`, `delta_step`) should be filled.	`0.99`
`delta_step`	Yes, if `strike_list` or `deltas` or the set of parameters (`f_log_m_min`, `f_log_m_max`, `f_log_m_step`) are not used. To be used along with `delta_min`, `delta_max`.	Step between two deltas (of a Call option) on the space grid. Either `strike_list` , (`f_log_m_min`, `f_log_m_max`, `f_log_m_step`), `deltas` or (`delta_min`, `delta_max`, `delta_step`) should be filled.

base

Yes

The desired base as the underlying of the options. See asset support above.

btc, eth

quote

Yes

The desired quote as the underlying of the options. See asset support above.

usd

exchanges

Yes

The desired exchange as source of options data. See exchange support above.

drbt

value_time

Yes

The time at which to compute implied volatilities The time t should be smaller than the lowest requested expiry.

2022-06-25T16:00:00.000Z

expiry_list

Yes, if the set of parameters (tte_min, tte_max, tte_step) is not used.

The expiries for which the implied volatilities are to be computed. Expiries can be listed or non-listed ones.

Expiries should be between minimum and maximum listed maturities on exchange. If not, a partial output will be returned.
Either expiry_list or (tte_min, tte_max, tte_step) should be filled.

expiry_list=2022-08-28T08:00:00.000Z, 2022-08-30T08:00:00.000Z or tte_min=0.034288&tte_max=1&tte_step=0.02

tte_min

Yes, if expiry_list is not used. To be used along with tte_max, tte_step.

Minimum time-to-expiry on the time grid.

Strictly positive value allowed.
If the `tte_min` is below the time to expiry associated with the minimum listed maturity, partial output will be returned.
Either expiry_list or (tte_min, tte_max, tte_step) should be filled.

0.034288

tte_max

Yes, if expiry_list is not used. To be used along with tte_min, tte_step.

Maximum time-to-expiry on the time grid.

Strictly positive value above the `tte_min`.
If the `tte_max` is above the time to expiry associated with the maximum listed maturity, partial output will be returned.

Either expiry_list or (tte_min, tte_max,tte_step) should be filled.

1

tte_step

Yes, if expiry_list is not used. To be used along with tte_min, tte_max.

Step between two time-to-expiries in time grid.

Strictly positive value allowed.
Either expiry_list or (tte_min, tte_max, tte_step) should be filled.

0.02

strike_list

Yes, if the set of parameters (f_log_min, f_log_max, f_log_step) or deltas or the set of parameters (delta_min, delta_max, delta_step) are not used.

The strike prices for which the implied volatilities are to be computed. Strike prices can be listed or non-listed ones.

Strictly positives values allowed.
Either strike_list , (f_log_m_min, f_log_m_max, f_log_m_step), deltas or (delta_min, delta_max, delta_step) should be filled.

strike_list=25000, 29150, 29155, 29160 or f_log_m_min=-1.5&f_log_m_max=1.5&f_log_m_step=0.05

f_log_m_min

Yes, if strike_list or deltas or the set of parameters (delta_min, delta_max, delta_step) are not used. To be used along with f_log_m_max, f_log_m_step.

Minimum forward log-moneyness on the space grid.

Either strike_list , (f_log_m_min, f_log_m_max, f_log_m_step), deltas or (delta_min, delta_max, delta_step) should be filled.

-1.5

f_log_m_max

Yes, if strike_list or deltas or the set of parameters (delta_min, delta_max, delta_step) are not used. To be used along with f_log_m_min, f_log_m_step.

Maximum forward log-moneyness on the space grid.

Either strike_list , (f_log_m_min, f_log_m_max, f_log_m_step), deltas or (delta_min, delta_max, delta_step) should be filled.

1

f_log_m_step

Yes, if strike_list or deltas or the set of parameters (delta_min, delta_max, delta_step) are not used. To be used along with f_log_m_min, f_log_m_max.

Step between two forward log moneyness in space grid.

Either strike_list , (f_log_m_min, f_log_m_max, f_log_m_step), deltas or (delta_min, delta_max, delta_step) should be filled.

0.02

deltas

Yes, if strike_list or the sets of parameters (delta_min, delta_max, delta_step) or (f_log_m_min, f_log_m_max, f_log_m_step) are not used.

The delta levels (of a Call option) for which the implied volatilities are to be computed.

Only delta values between 0.01 and 0.99 are allowed.
Either strike_list , (f_log_m_min, f_log_m_max, f_log_m_step), deltas or (delta_min, delta_max, delta_step) should be filled.

deltas=0.25,0.5,0.75

delta_min

Yes, if strike_list or deltas or the set of parameters (f_log_m_min, f_log_m_max, f_log_m_step) are not used. To be used along with delta_max, delta_step.

Minimum delta (of a Call option) on the space grid.

Only delta values between 0.01 and 0.99 are allowed.
Either strike_list , (f_log_m_min, f_log_m_max, f_log_m_step), deltas or (delta_min, delta_max, delta_step) should be filled.

0.01

delta_max

Yes, if strike_list or deltas or the set of parameters (f_log_m_min, f_log_m_max, f_log_m_step) are not used. To be used along with delta_min, delta_step.

Maximum delta (of a Call option) on the space grid.

Only delta values between 0.01 and 0.99 are allowed.
Either strike_list , (f_log_m_min, f_log_m_max, f_log_m_step), deltas or (delta_min, delta_max, delta_step) should be filled.

0.99

delta_step

Yes, if strike_list or deltas or the set of parameters (f_log_m_min, f_log_m_max, f_log_m_step) are not used. To be used along with delta_min, delta_max.

Step between two deltas (of a Call option) on the space grid.

Either strike_list , (f_log_m_min, f_log_m_max, f_log_m_step), deltas or (delta_min, delta_max, delta_step) should be filled.

Fields

Field Description Example

Field	Description	Example
complete_output	This indicates whether the output covers the entire requested range within the listed expiries, or only the valid subset.	True
`value_time`	The time in parameter	`2022-06-25T16:00:00Z`
`expiry`	The expiry at which the IV has been interpolated.	`2022-08-28T08:00:00Z`
`time_to_expiry`	The associated time-to-expiry (in year).	`0.17442922374429223`
`strike`	The strike at which the IV has been computed. Not provided when the input is a delta list.	`265.88827409960714`
`forward_log_moneyness`	The associated forward log-moneyness. Not provided when the input is a delta list.	`-1.5`
`implied_volatility`	The calibrated and interpolated implied volatilities.	`1.8088997727784055`
`delta`	The first derivative of the price (of a Call option) with regards to the underlying price	`-0.009058250602524742`
`gamma`	The second derivative of the price with regards to the underlying price	`0.000027152549142705487`
`interest_rate`	The implied interest rate.	`0.14954983972466698`
`current_spot`	The underlying spot price at the value timestamp.	`71717`

complete_output

This indicates whether the output covers the entire requested range within the listed expiries, or only the valid subset.

True

value_time

The time in parameter

2022-06-25T16:00:00Z

expiry

The expiry at which the IV has been interpolated.

2022-08-28T08:00:00Z

time_to_expiry

The associated time-to-expiry (in year).

0.17442922374429223

strike

The strike at which the IV has been computed. Not provided when the input is a delta list.

265.88827409960714

forward_log_moneyness

The associated forward log-moneyness. Not provided when the input is a delta list.

-1.5

implied_volatility

The calibrated and interpolated implied volatilities.

1.8088997727784055

delta

The first derivative of the price (of a Call option) with regards to the underlying price

-0.009058250602524742

gamma

The second derivative of the price with regards to the underlying price

0.000027152549142705487

interest_rate

The implied interest rate.

0.14954983972466698

current_spot

The underlying spot price at the value timestamp.

71717

Request example

curl --compressed -H 'Accept: application/json' -H 'X-Api-Key: <client-api-key>' \
'https://us.market-api.kaiko.io/v2/data/analytics.v2/implied_volatility_surface?base=btc&quote=usd&tte_step=0.02&exchanges=drbt&f_log_m_min=-0.5&f_log_m_max=0.5&f_log_m_step=0.5&value_time=2024-06-23T04:37:00.000Z&tte_min=0.021390791476407916&tte_max=0.5583770928462709'

Response example

{
    "query": {
        "base": "btc",
        "quote": "usd",
        "exchanges": [
            "drbt"
        ],
        "value_time": "2024-06-23T04:37:00.000Z",
        "data_version": "v2",
        "commodity": "analytics",
        "request_time": "2024-06-24T19:41:13.663Z"
    },
    "time": "2024-06-24T19:41:13.663Z",
    "timestamp": 1719258074476,
    "complete_output": True,
    "data": [
        {
            "value_time": "2024-06-23T04:37:00.000Z",
            "expiry": "2024-07-01T00:00:00.000Z",
            "time_to_expiry": 0.021390791476407916,
            "implied_volatilities": [
                {
                    "strike": 64375.48,
                    "forward_log_moneyness": 0,
                    "implied_volatility": 0.3835618642895939,
                    "delta": 0.5111885027781751,
                    "gamma": 0.00011042563280163218,
                    "interest_rate": 0.10447166350422607,
                    "current_spot": 64347.800559330484
                }
            ]
        },
        {
            "value_time": "2024-06-23T04:37:00.000Z",
            "expiry": "2024-07-08T07:12:00.000Z",
            "time_to_expiry": 0.041390791476407916,
            "implied_volatilities": [
                {
                    "strike": 64375.48,
                    "forward_log_moneyness": 0,
                    "implied_volatility": 0.40153413462466386,
                    "delta": 0.5162904717206296,
                    "gamma": 0.00007579716641505098,
                    "interest_rate": 0.08976789979931356,
                    "current_spot": 64347.800559330375
                }
            ]
        }
    ]
}

PreviousIV Smile NextRisk Metrics

Last updated 12 days ago