# Option smile

IV-by-strike for a single expiration on the latest snapshot. Both option types returned, ordered by strike. Designed for direct plotting (`x = strike, y = mark_iv`) with optional bid/ask brackets.

The endpoint is a focused projection of [Option chain](/data/option-chain.md) — same underlying data, narrower column set, server-side filtered to non-zero IV.

## SQL API

The smile shape comes from the same `api.option_chains` table:

```sql
WITH (
  SELECT max(timestamp)
  FROM api.option_chains
  WHERE exchange = 'deribit' AND underlying_asset = 'BTC'
) AS latest_ts
SELECT strike, option_type, mark_iv, bid_iv, ask_iv, delta, underlying_price
FROM api.option_chains
WHERE exchange = 'deribit'
  AND underlying_asset = 'BTC'
  AND toDate(expiration) = toDate('2026-06-26')
  AND timestamp = latest_ts
  AND mark_iv != 0
ORDER BY strike, option_type
```

Plot the result as a scatter / line over `(strike, mark_iv)` to see the smile. For an OTM-only wing curve, filter to `option_type = 'C' AND strike > underlying_price` (calls above spot) and `option_type = 'P' AND strike < underlying_price` (puts below spot).

### Cross-expiration vol surface

To build a vol surface, query each expiration in turn (or join with `dte` in the result):

```sql
WITH (
  SELECT max(timestamp)
  FROM api.option_chains
  WHERE exchange = 'deribit' AND underlying_asset = 'BTC'
) AS latest_ts
SELECT
  toDate(expiration)                                AS expiry,
  strike / toFloat64(underlying_price)              AS moneyness,
  mark_iv                                           AS iv,
  toUInt32(date_diff('day', timestamp, expiration)) AS dte
FROM api.option_chains
WHERE exchange = 'deribit'
  AND underlying_asset = 'BTC'
  AND mark_iv != 0
  AND timestamp = latest_ts
ORDER BY expiry, moneyness
```

## REST API

## Get Volatility Smile

> IV-by-strike for a single expiration on the latest snapshot. Both option types (C/P) returned, ordered by strike. Designed for direct plotting (x=strike, y=mark\_iv).<br>

```json
{"openapi":"3.1.1","info":{"title":"Koinju Market Data API","version":"1.0.0"},"servers":[{"url":"https://api.koinju.io","description":"Koinju API Server"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Required for /ohlcv and /trade endpoints.\nPass your API key in the x-api-key header.\nPublic /market/* endpoints do not require authentication.\n"}},"schemas":{"OptionSmileRow":{"type":"object","properties":{"strike":{"type":"number","format":"decimal","description":"Strike price"},"option_type":{"type":"string","enum":["C","P"],"description":"Call or Put"},"mark_iv":{"type":"number","format":"decimal","description":"Mark implied volatility (annualized %)"},"bid_iv":{"type":"number","format":"decimal","description":"Bid IV"},"ask_iv":{"type":"number","format":"decimal","description":"Ask IV"},"delta":{"type":"number","format":"decimal","description":"Delta"},"underlying_price":{"type":"number","format":"decimal","description":"Spot/index price of the underlying at snapshot time"},"dte":{"type":"integer","description":"Days-to-expiry"}}}}},"paths":{"/option/smile":{"get":{"summary":"Get Volatility Smile","description":"IV-by-strike for a single expiration on the latest snapshot. Both option types (C/P) returned, ordered by strike. Designed for direct plotting (x=strike, y=mark_iv).\n","tags":["market_data"],"parameters":[{"name":"exchange","in":"query","required":true,"schema":{"type":"string","enum":["deribit","binance","okx","bybit"]},"description":"Exchange — one of `deribit`, `binance`, `okx`, `bybit`."},{"name":"underlying_asset","in":"query","required":true,"schema":{"type":"string"},"description":"Underlying coin (e.g. `BTC`)."},{"name":"expiration","in":"query","required":true,"schema":{"type":"string","format":"date"},"description":"Expiry date, ISO (`YYYY-MM-DD`). Required."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/OptionSmileRow"}}}}}}}}}}
```


---

# 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.koinju.io/data/option-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.