# 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.

{% 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 %}