# Implied volatility calculation - smile

{% hint style="info" %}
If you need implied volatilities for expiry dates that are not listed, you can use the "implied volatility surface" endpoint to calculate this.
{% endhint %}

## What is this endpoint for?

The IV Smile endpoint lets you calculate volatility on a minute-by-minute basis from options market prices. The endpoint returns a volatility curve for a specific expiry date. 

You can get volatility estimates by providing the following information:

* Strikes
* Forward-log-moneyness
* Deltas

The calculation methodology leverages space interpolation.

**Currently supported assets and exchanges:**

* BTC, ETH, SOL, and, 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.

Read our Implied Volatility Methodology [here](https://25446524.fs1.hubspotusercontent-eu1.net/hubfs/25446524/Factsheets/Kaiko%20Implied%20Volatility%20Methodology.pdf). 

{% hint style="warning" %}
Short listed-maturities (e.g. 7 days time-to-maturity) are only available for individual exchanges.
{% endhint %}

### Endpoint

{% code overflow="wrap" %}

```http
https://{eu/us}.market-api.kaiko.io/v2/data/analytics.v2/implied_volatility_smile
```

{% endcode %}

### Path Parameters

| Parameter | Required? | Example                       |
| --------- | --------- | ----------------------------- |
| `region`  | Yes       | Choose between `eu` and `us`. |

### Query Parameters

<table><thead><tr><th width="130">Parameter</th><th width="141">Required</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td><code>base</code></td><td>Yes</td><td>The desired base as the underlying of the options.<br><br>See supported assets above.</td><td><code>btc</code>, <code>eth</code></td></tr><tr><td><code>quote</code></td><td>Yes</td><td>The desired quote as the underlying of the options.<br><br><code>usd</code> or <code>usdc</code></td><td><code>usd</code></td></tr><tr><td><code>value_time</code></td><td>Yes</td><td>The time at which to compute implied volatilities<br><br>The time <em>t</em> should be smaller than the expiry <em>T</em></td><td><code>2022-09-20T16:15:00.000Z</code></td></tr><tr><td><code>expiry</code></td><td>Yes</td><td>The expiry for which the implied volatilities are to be computed<br><br>Must be an existing expiry on the selected exchange and tradable at the time of the computation.</td><td><code>2022-12-30T08:00:00.000Z</code></td></tr><tr><td><code>strikes</code></td><td>Yes, if neither <code>forward_log_moneynesses</code> nor <code>deltas</code> parameters are used.</td><td>The strike prices for which the implied volatilities are to be computed. Strike prices can be existing or non-existing ones (space interpolation included)<br><br>Either <code>strikes</code> or <code>forward_log_moneynesses</code> or deltas should be filled.</td><td>singular: <code>10000</code><br>plural: <code>10000,15000,20000</code></td></tr><tr><td><code>forward_log_moneynesses</code></td><td>Yes, if neither <code>strikes</code> nor <code>deltas</code> parameters are used.</td><td>The forward log moneyness for which the implied volatilities are to be computed.<br><br>Either <code>strikes, forward_log_moneynesses</code> or <code>deltas</code> should be filled.</td><td>singular: <code>1</code><br>plural: <code>-1,-0.5,0,0.5,1</code></td></tr><tr><td><code>deltas</code></td><td>Yes, if neither <code>forward_log_moneynesses</code> nor <code>strikes</code> parameters are used.</td><td>The delta levels (of a Call option) for which the implied volatilities are to be computed.<br><br>Either <code>strikes, forward_log_moneynesses</code> or <code>deltas</code> should be filled.</td><td></td></tr><tr><td><code>exchanges</code></td><td>No</td><td>The desired exchange as source of options data.<br><br>See supported exchanges above.</td><td><code>drbt</code></td></tr></tbody></table>

### Fields

<table><thead><tr><th width="165">Field</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td><code>value_time</code></td><td>The time in parameter</td><td><code>2022-09-20T16:15:00.000Z</code></td></tr><tr><td><code>expiry</code></td><td>The expiry in parameter</td><td><code>2022-12-30T00:00:00.000Z</code></td></tr><tr><td><code>time_to_expiry</code></td><td>The associated time to expiry in year</td><td><code>0.27580868156450355</code></td></tr><tr><td><code>implied_volatilities</code></td><td>The list of requested implied volatilities</td><td><code>[{"strike": 40000,</code><br><code>"forward_log_moneyness": 0.7348555803648208,</code><br><code>"implied_volatility": 0.7341747093260883,</code><br><code>"delta": 0.04334612697660922,</code><br><code>"gamma": 0.000012437991693543254},</code><br><code>{"strike": 20000,</code><br><code>"forward_log_moneyness": 0.041708399804875465,</code><br><code>"implied_volatility": 0.6670092468551713,</code><br><code>"delta": 0.5223606946028295,</code><br><code>"gamma": 0.00005929353471794603}, ... ]</code></td></tr><tr><td><code>delta</code></td><td>The first derivative of the price with regards to the underlying price.</td><td><code>2.8863019124747424e-7</code></td></tr><tr><td><code>gamma</code></td><td>The second derivative of the price with regards to the underlying price.</td><td><code>2.416523346501216e-10</code></td></tr><tr><td><code>current_spot</code></td><td>The underlying spot price at the value timestamp.</td><td><code>71717</code></td></tr><tr><td><code>interest_rate</code></td><td>The implied interest rate.</td><td><code>0.14954983972466698</code></td></tr></tbody></table>

### Request examples

{% tabs %}
{% tab title="cURL" %}
**Use this example to calculate IV using deltas.**

{% code overflow="wrap" %}

```url
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_smile?base=btc&quote=usd&value_time=2024-06-07T12:00:00.000Z&expiry=2024-06-28T00:00:00.000Z&exchanges=drbt&deltas=0.25,0.5,0.75'
```

{% endcode %}

**Use this example to calculate IV using forward log moneyness.**

{% code overflow="wrap" %}

```url
https://us.market-api.kaiko.io/v2/data/analytics.v2/implied_volatility_smile?base=btc&quote=usd&exchanges=drbt,okex&value_time=2024-09-12T10:00:00.000Z&expiry=2024-09-27T08:00:00.000Z&forward_log_moneynesses=-1,-0.5,0,0.5,1
```

{% endcode %}

**Use this example to calculate IV using strikes.**

{% code overflow="wrap" %}

```url
https://us.market-api.kaiko.io/v2/data/analytics.v2/implied_volatility_smile?base=btc&quote=usd&exchanges=drbt&value_time=2024-09-12T10:00:00.000Z&expiry=2024-09-27T08:00:00.000Z&strikes=30000,50000,60000,70000,90000
```

{% endcode %}
{% endtab %}

{% tab title="Python (Deltas)" %}
**Use this example to calculate IV using deltas**&#x20;

{% code overflow="wrap" %}

```python
##### 1. Import dependencies #####
import requests
import pandas as pd

##### 2. Choose the value of the query's parameters #####
# ---- Required parameters ---- #
base = "btc"
quote = "usd"
value_time = "2024-06-07T12:00:00.000Z"
expiry = "2024-06-28T00:00:00.000Z"
deltas = "0.25,0.5,0.75"

# ---- Optional parameters ---- #
exchanges = "drbt"

# ---- API key configuration ---- #
api_key = "YOUR_API_KEY"

##### 3. Get the data #####
# ---- Function to run an API call ---- # 
# Get the data in a dataframe --------- # 

def get_kaiko_data(api_key: str, base: str, quote: str, value_time: str, expiry: str, deltas: str, exchanges: str = None):
    headers = {'Accept': 'application/json', 'X-Api-Key': api_key}
    
    url = f'https://us.market-api.kaiko.io/v2/data/analytics.v2/implied_volatility_smile'
    params = {
        "base": base,
        "quote": quote,
        "value_time": value_time,
        "expiry": expiry,
        "deltas": deltas,
        "exchanges": exchanges
    }

    try:
        res = requests.get(url, headers=headers, params=params)
        res.raise_for_status() 
        data = res.json()
        if 'data' not in data:
            print("No data returned.")
            return pd.DataFrame() 
        df = pd.DataFrame(data['data'])

        # Handle pagination with continuation token
        while 'next_url' in data:
            next_url = data['next_url']
            if next_url is None:
                break
            res = requests.get(next_url, headers=headers)
            res.raise_for_status()
            data = res.json()
            if 'data' in data:
                df = pd.concat([df, pd.DataFrame(data['data'])], ignore_index=True)
        return df

    except requests.exceptions.RequestException as e:
        print(f"API request error: {e}")
        return pd.DataFrame() 

# ---- Get the data ---- #
df = get_kaiko_data(api_key=api_key, base=base, quote=quote, value_time=value_time, expiry=expiry, deltas=deltas, exchanges=exchanges)
print (df)
```

{% endcode %}
{% endtab %}

{% tab title="Python (Forward log moneyness)" %}
**Use this example to calculate IV using forward log moneyness**

```python
##### 1. Import dependencies #####
import requests
import pandas as pd

##### 2. Choose the value of the query's parameters #####
# ---- Required parameters ---- #
base = "btc"
quote = "usd"
value_time = "2022-09-20T16:15:00.000Z"
expiry = "2022-12-30T08:00:00.000Z"
forward_log_moneynesses = "-1,-0.5,0,0.5,1"

# ---- Optional parameters ---- #
exchanges = "drbt"

# ---- API key configuration ---- #
api_key = "YOUR_API_KEY"

##### 3. Get the data #####
# ---- Function to run an API call ---- # 
# Get the data in a dataframe --------- # 

def get_kaiko_data(api_key: str, base: str, quote: str, value_time: str, expiry: str, forward_log_moneynesses: str, exchanges: str = None):
    headers = {'Accept': 'application/json', 'X-Api-Key': api_key}
    
    url = f'https://us.market-api.kaiko.io/v2/data/analytics.v2/implied_volatility_smile'
    params = {
        "base": base,
        "quote": quote,
        "value_time": value_time,
        "expiry": expiry,
        "forward_log_moneynesses": forward_log_moneynesses,
        "exchanges": exchanges
    }

    try:
        res = requests.get(url, headers=headers, params=params)
        res.raise_for_status() 
        data = res.json()
        if 'data' not in data:
            print("No data returned.")
            return pd.DataFrame() 
        df = pd.DataFrame(data['data'])

        # Handle pagination with continuation token
        while 'next_url' in data:
            next_url = data['next_url']
            if next_url is None:
                break
            res = requests.get(next_url, headers=headers)
            res.raise_for_status()
            data = res.json()
            if 'data' in data:
                df = pd.concat([df, pd.DataFrame(data['data'])], ignore_index=True)
        return df

    except requests.exceptions.RequestException as e:
        print(f"API request error: {e}")
        return pd.DataFrame() 

# ---- Get the data ---- #
df = get_kaiko_data(api_key=api_key, base=base, quote=quote, value_time=value_time, expiry=expiry, forward_log_moneynesses=forward_log_moneynesses, exchanges=exchanges)
print (df)
```

{% endtab %}

{% tab title="Python (Strikes)" %}
**Use this example to calculate IV using forward log moneyness**

```python
##### 1. Import dependencies #####
import requests
import pandas as pd

##### 2. Choose the value of the query's parameters #####
# ---- Required parameters ---- #
base = "btc"
quote = "usd"
value_time = "2022-09-20T16:15:00.000Z"
expiry = "2022-12-30T08:00:00.000Z"
strikes = "10000,15000,20000"

# ---- Optional parameters ---- #
exchanges = "drbt"

# ---- API key configuration ---- #
api_key = "YOUR_API_KEY"

##### 3. Get the data #####
# ---- Function to run an API call ---- # 
# Get the data in a dataframe --------- # 

def get_kaiko_data(api_key: str, base: str, quote: str, value_time: str, expiry: str, strikes: str, exchanges: str = None):
    headers = {'Accept': 'application/json', 'X-Api-Key': api_key}
    
    url = f'https://us.market-api.kaiko.io/v2/data/analytics.v2/implied_volatility_smile'
    params = {
        "base": base,
        "quote": quote,
        "value_time": value_time,
        "expiry": expiry,
        "strikes": strikes,
        "exchanges": exchanges
    }

    try:
        res = requests.get(url, headers=headers, params=params)
        res.raise_for_status() 
        data = res.json()
        if 'data' not in data:
            print("No data returned.")
            return pd.DataFrame() 
        df = pd.DataFrame(data['data'])

        # Handle pagination with continuation token
        while 'next_url' in data:
            next_url = data['next_url']
            if next_url is None:
                break
            res = requests.get(next_url, headers=headers)
            res.raise_for_status()
            data = res.json()
            if 'data' in data:
                df = pd.concat([df, pd.DataFrame(data['data'])], ignore_index=True)
        return df

    except requests.exceptions.RequestException as e:
        print(f"API request error: {e}")
        return pd.DataFrame() 

# ---- Get the data ---- #
df = get_kaiko_data(api_key=api_key, base=base, quote=quote, value_time=value_time, expiry=expiry, strikes=strikes, exchanges=exchanges)
print (df)
```

{% endtab %}
{% endtabs %}

### Response examples

{% tabs %}
{% tab title="Deltas" %}

```json
{
    "query": {
        "base": "btc",
        "quote": "usd",
        "exchanges": [
            "drbt",
            "okex"
        ],
        "value_time": "2024-06-07T12:00:00.000Z",
        "expiry": "2024-06-28T00:00:00.000Z",
        "data_version": "v2",
        "commodity": "analytics",
        "request_time": "2024-06-24T12:30:09.700Z",
        "sources": "false"
    },
    "time": "2024-06-24T12:30:10.147Z",
    "data": [
        {
            "value_time": "2024-06-07T12:00:00.000Z",
            "expiry": "2024-06-28T00:00:00.000Z",
            "time_to_expiry": 0.056164383561643834,
            "implied_volatilities": [
                {
                    "strike": 72853.3324003775,
                    "forward_log_moneyness": 0.007321081822738051,
                    "implied_volatility": 0.5105897940662363,
                    "delta": 0.5,
                    "gamma": 0.000045971145294598765,
                    "current_spot": 71717,
                    "interest_rate": 0.14954983972466698
                },
                {
                    "strike": 79392.23132701412,
                    "forward_log_moneyness": 0.09327332815155387,
                    "implied_volatility": 0.5335098490669691,
                    "delta": 0.25,
                    "gamma": 0.00003504506121504308,
                    "current_spot": 71717,
                    "interest_rate": 0.14954983972466698
                },
                {
                    "strike": 67169.33106494324,
                    "forward_log_moneyness": -0.07391043269308284,
                    "implied_volatility": 0.5076566142080143,
                    "delta": 0.75,
                    "gamma": 0.000036829787686483384,
                    "current_spot": 71717,
                    "interest_rate": 0.14954983972466698
                }
            ]
        }
    ],
    "exchanges": [
        "drbt",
        "okex"
    ]
}

```

{% endtab %}

{% tab title="Forward log moneyness" %}

```json
{
   "query": {
      "base": "btc",
      "quote": "usd",
      "exchanges": [
         "drbt",
         "okex"
      ],
      "value_time": "2024-09-12T10:00:00.000Z",
      "expiry": "2024-09-27T08:00:00.000Z",
      "data_version": "v2",
      "commodity": "analytics",
      "request_time": "2024-09-16T10:08:13.297Z",
      "sources": "false"
   },
   "time": "2024-09-16T10:08:13.510Z",
   "data": [
      {
         "value_time": "2024-09-12T10:00:00.000Z",
         "expiry": "2024-09-27T00:00:00.000Z",
         "time_to_expiry": 0.03995433789954338,
         "implied_volatilities": [
            {
               "strike": 21393.433382294108,
               "forward_log_moneyness": -1,
               "implied_volatility": 1.333640363610205,
               "delta": 0.9999487436462999,
               "gamma": 1.3636212810241294E-8,
               "current_spot": 58033.01112255454,
               "interest_rate": 0.051859643540835755
            },
            {
               "strike": 35271.80867069449,
               "forward_log_moneyness": -0.5,
               "implied_volatility": 0.9596570717413877,
               "delta": 0.9965589532046168,
               "gamma": 9.298329941261203E-7,
               "current_spot": 58033.01112255454,
               "interest_rate": 0.051859643540835755
            },
            {
               "strike": 58153.381211439206,
               "forward_log_moneyness": 0,
               "implied_volatility": 0.5101368982713104,
               "delta": 0.5203310896967671,
               "gamma": 6.732894295644585E-5,
               "current_spot": 58033.01112255454,
               "interest_rate": 0.051859643540835755
            },
            {
               "strike": 95878.71656643301,
               "forward_log_moneyness": 0.5,
               "implied_volatility": 0.8386751286583922,
               "delta": 0.0018731164887705876,
               "gamma": 6.140349526013891E-7,
               "current_spot": 58033.01112255454,
               "interest_rate": 0.051859643540835755
            },
            {
               "strike": 158077.27941050686,
               "forward_log_moneyness": 1,
               "implied_volatility": 1.1585659255535645,
               "delta": 1.3207614779298105E-5,
               "gamma": 4.342680303635139E-9,
               "current_spot": 58033.01112255454,
               "interest_rate": 0.051859643540835755
            }
         ]
      }
   ]
}
```

{% endtab %}

{% tab title="Strikes" %}

```json
{
   "query": {
      "base": "btc",
      "quote": "usd",
      "exchanges": [
         "drbt"
      ],
      "value_time": "2024-09-12T10:00:00.000Z",
      "expiry": "2024-09-27T08:00:00.000Z",
      "data_version": "v2",
      "commodity": "analytics",
      "request_time": "2024-09-16T10:16:06.767Z",
      "sources": "false"
   },
   "time": "2024-09-16T10:16:07.109Z",
   "data": [
      {
         "value_time": "2024-09-12T10:00:00.000Z",
         "expiry": "2024-09-27T08:00:00.000Z",
         "time_to_expiry": 0.0408675799086758,
         "implied_volatilities": [
            {
               "strike": 30000,
               "forward_log_moneyness": -0.6621439523959698,
               "implied_volatility": 1.0918347265102102,
               "delta": 0.999065374274305,
               "gamma": 2.470728795941105E-7,
               "current_spot": 58026.01780838792,
               "interest_rate": 0.0599458347465653
            },
            {
               "strike": 50000,
               "forward_log_moneyness": -0.15131832862997915,
               "implied_volatility": 0.6151097548518855,
               "delta": 0.8995619045026346,
               "gamma": 2.4400231724112595E-5,
               "current_spot": 58026.01780838792,
               "interest_rate": 0.0599458347465653
            },
            {
               "strike": 60000,
               "forward_log_moneyness": 0.031003228163975546,
               "implied_volatility": 0.5087453039141314,
               "delta": 0.40128287640417803,
               "gamma": 6.479219462479912E-5,
               "current_spot": 58026.01780838792,
               "interest_rate": 0.0599458347465653
            },
            {
               "strike": 70000,
               "forward_log_moneyness": 0.18515390799123382,
               "implied_volatility": 0.5834792805075438,
               "delta": 0.06542894780360681,
               "gamma": 1.861991887220773E-5,
               "current_spot": 58026.01780838792,
               "interest_rate": 0.0599458347465653
            },
            {
               "strike": 90000,
               "forward_log_moneyness": 0.4364683362721398,
               "implied_volatility": 0.7752384746098042,
               "delta": 0.0033982150399509137,
               "gamma": 1.125492902360329E-6,
               "current_spot": 58026.01780838792,
               "interest_rate": 0.0599458347465653
            }
         ]
      }
   ]
}
Shared in

```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.kaiko.com/rest-api/analytics-solutions/kaiko-derivatives-risk-indicators/implied-volatility-calculation-smile.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.