Options

The options endpoint provides derivatives analytics across 22 chart types, sourced from Deribit (currently the only supported options venue). Query implied volatility term structures, vol surfaces, skew, open interest distributions, put/call ratios, realized volatility, Z-scores, and gamma exposure.

Get options data

Returns time-series or snapshot data for a specific options chart. Charts fall into two categories: time-series charts respect the timeframe parameter and return historical data, while snapshot charts return the latest available data regardless of timeframe.

Query parameters

Name
chart
Type
string
Description
The chart to fetch. One of: atm-iv, iv-term-structure, vol-smile, vol-surface, vol-skew, term-structure-slope, spot-vol-correlation, oi-by-strike, oi-by-expiry, put-call-oi-ratio, max-pain, top-volume, put-call-volume-ratio, options-flow, exchange-volume, realized-vol, iv-vs-rv, zscore-iv, zscore-rv, zscore-iv-rv, gex, vol-cones.
Name
coin
Type
string
Description
Asset ticker (BTC or ETH). Defaults to BTC.
Name
timeframe
Type
string
Description
Lookback window. One of 1W, 1M, 3M, 6M, 1Y, 3Y, ALL. Defaults to 3M. Ignored for snapshot charts.
Name
exchanges
Type
string
Description
Comma-separated exchange filter. Only Deribit is supported today; the parameter is reserved for forward-compatibility when additional venues are integrated.

Response fields

Name
chart
Type
string
Description
The chart ID that was requested.
Name
coin
Type
string
Description
The asset ticker.
Name
timeframe
Type
string
Description
The timeframe that was applied.
Name
data
Type
array
Description
Array of data points. Shape varies by chart type.
Name
coverage
Type
object
Description
Contains availableSince (ISO timestamp or null) and availableTimeframes (array of valid timeframe strings). Only populated for time-series charts.
Name
source
Type
string
Description
Always "supabase".

Request

GET

/v1/options/data

curl -G https://www.sharpe.ai/api/v1/options/data \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -d chart=atm-iv \
  -d coin=BTC \
  -d timeframe=3M

{
  "data": {
    "chart": "atm-iv",
    "coin": "BTC",
    "timeframe": "3M",
    "data": [
      {
        "fetched_at": "2026-03-01T00:00:00Z",
        "atm_iv_1w": 0.42,
        "atm_iv_1m": 0.48,
        "atm_iv_3m": 0.52,
        "atm_iv_6m": 0.55,
        "atm_iv_1y": 0.58
      },
      {
        "fetched_at": "2026-03-02T00:00:00Z",
        "atm_iv_1w": 0.45,
        "atm_iv_1m": 0.50,
        "atm_iv_3m": 0.53,
        "atm_iv_6m": 0.56,
        "atm_iv_1y": 0.59
      }
    ],
    "coverage": {
      "availableSince": "2025-06-01T00:00:00Z",
      "availableTimeframes": ["1W", "1M", "3M", "6M", "1Y"]
    },
    "source": "supabase"
  },
  "meta": {
    "request_id": "req_abc123def456ghij",
    "timestamp": "2026-03-28T12:00:00Z"
  }
}

Time-series charts

These charts return historical data from options_historical and respect the timeframe parameter. Data is downsampled to one point per bucket (hourly for 1W, daily for longer periods).

Volatility time series

Charts: atm-iv, vol-skew, term-structure-slope, spot-vol-correlation, realized-vol, iv-vs-rv, vol-cones.

vol-cones always returns 400 days of data to compute proper percentile cone statistics, regardless of the timeframe value.

Name
fetched_at
Type
string
Description
ISO 8601 timestamp.
Name
atm_iv_1w
Type
number
Description
ATM implied volatility, 1-week tenor.
Name
atm_iv_1m
Type
number
Description
ATM implied volatility, 1-month tenor.
Name
atm_iv_3m
Type
number
Description
ATM implied volatility, 3-month tenor.
Name
atm_iv_6m
Type
number
Description
ATM implied volatility, 6-month tenor.
Name
atm_iv_1y
Type
number
Description
ATM implied volatility, 1-year tenor.
Name
skew_1w
Type
number
Description
25-delta skew, 1-week tenor.
Name
skew_1m
Type
number
Description
25-delta skew, 1-month tenor.
Name
skew_3m
Type
number
Description
25-delta skew, 3-month tenor.
Name
skew_6m
Type
number
Description
25-delta skew, 6-month tenor.
Name
skew_1y
Type
number
Description
25-delta skew, 1-year tenor.
Name
slope
Type
number
Description
Term structure slope.
Name
spot_vol_corr
Type
number
Description
Spot-vol correlation.
Name
rv_1w
Type
number
Description
Realized volatility, 1-week window.
Name
rv_1m
Type
number
Description
Realized volatility, 1-month window.
Name
rv_3m
Type
number
Description
Realized volatility, 3-month window.
Name
rv_6m
Type
number
Description
Realized volatility, 6-month window.
Name
rv_1y
Type
number
Description
Realized volatility, 1-year window.
Name
put_call_oi_ratio
Type
number
Description
Put/call open interest ratio.
Name
put_call_vol_ratio
Type
number
Description
Put/call volume ratio.

Z-score charts

Charts: zscore-iv, zscore-rv, zscore-iv-rv. Computed as rolling 60-period Z-scores with a minimum of 20 observations.

Name
fetched_at
Type
string
Description
ISO 8601 timestamp.
Name
zscore
Type
number
Description
Rolling Z-score value.

{
  "data": {
    "chart": "zscore-iv",
    "coin": "BTC",
    "timeframe": "3M",
    "data": [
      {
        "fetched_at": "2026-03-01T00:00:00Z",
        "zscore": 1.23
      },
      {
        "fetched_at": "2026-03-02T00:00:00Z",
        "zscore": 0.87
      }
    ],
    "coverage": {
      "availableSince": "2025-06-01T00:00:00Z",
      "availableTimeframes": ["1W", "1M", "3M", "6M", "1Y"]
    },
    "source": "supabase"
  },
  "meta": {
    "request_id": "req_def456ghi789jklm",
    "timestamp": "2026-03-28T12:00:00Z"
  }
}

{
  "data": {
    "chart": "iv-vs-rv",
    "coin": "ETH",
    "timeframe": "1M",
    "data": [
      {
        "fetched_at": "2026-03-15T00:00:00Z",
        "atm_iv_1w": 0.55,
        "atm_iv_1m": 0.60,
        "rv_1w": 0.48,
        "rv_1m": 0.52
      }
    ],
    "coverage": {
      "availableSince": "2025-06-01T00:00:00Z",
      "availableTimeframes": ["1W", "1M", "3M", "6M"]
    },
    "source": "supabase"
  },
  "meta": {
    "request_id": "req_ghi789jkl012mnop",
    "timestamp": "2026-03-28T12:00:00Z"
  }
}

Snapshot charts

These charts return the latest available data point. The timeframe parameter is ignored.

IV term structure / OI by expiry

Charts: iv-term-structure, oi-by-expiry. Returns per-expiry aggregates from the latest snapshot.

Name
exchange
Type
string
Description
Exchange name (e.g., Deribit).
Name
expiry_date
Type
string
Description
Option expiry date.
Name
days_to_expiry
Type
number
Description
Days until expiry.
Name
atm_iv
Type
number
Description
ATM implied volatility for this expiry.
Name
forward_iv
Type
number
Description
Forward implied volatility.
Name
skew_25d
Type
number
Description
25-delta skew.
Name
rr25
Type
number
Description
25-delta risk reversal.
Name
bf25
Type
number
Description
25-delta butterfly.
Name
total_oi_usd
Type
number
Description
Total open interest in USD.
Name
put_oi_usd
Type
number
Description
Put open interest in USD.
Name
call_oi_usd
Type
number
Description
Call open interest in USD.
Name
total_volume_usd
Type
number
Description
Total volume in USD.
Name
put_volume_usd
Type
number
Description
Put volume in USD.
Name
call_volume_usd
Type
number
Description
Call volume in USD.
Name
put_call_ratio
Type
number
Description
Put/call ratio for this expiry.
Name
underlying_price
Type
number
Description
Underlying spot price at snapshot time.
Name
fetched_at
Type
string
Description
ISO 8601 snapshot timestamp.

Vol smile / Vol surface

Charts: vol-smile, vol-surface. Returns per-strike IV data.

Name
strike
Type
number
Description
Option strike price.
Name
mark_iv
Type
number
Description
Mark implied volatility.
Name
bid_iv
Type
number
Description
Bid implied volatility.
Name
ask_iv
Type
number
Description
Ask implied volatility.
Name
option_type
Type
string
Description
"call" or "put".
Name
delta
Type
number
Description
Option delta.
Name
expiry_date
Type
string
Description
Option expiry date.
Name
days_to_expiry
Type
number
Description
Days until expiry. Only present for vol-surface.
Name
underlying_price
Type
number
Description
Underlying spot price.
Name
fetched_at
Type
string
Description
ISO 8601 snapshot timestamp.

OI by strike

Chart: oi-by-strike. Aggregated across all expiries.

Name
strike
Type
number
Description
Strike price.
Name
call_oi_usd
Type
number
Description
Call open interest in USD at this strike.
Name
put_oi_usd
Type
number
Description
Put open interest in USD at this strike.

Gamma exposure (GEX)

Chart: gex. Per-strike gamma exposure from the latest snapshot.

Name
strike
Type
number
Description
Strike price.
Name
option_type
Type
string
Description
"call" or "put".
Name
delta
Type
number
Description
Option delta.
Name
gamma
Type
number
Description
Option gamma.
Name
oi
Type
number
Description
Open interest in contracts.
Name
oi_usd
Type
number
Description
Open interest in USD.
Name
expiry_date
Type
string
Description
Option expiry date.

Block trades / options flow

Chart: options-flow. Returns the last 24 hours of block trades, ordered by size. Limited to 100 results.

Name
exchange
Type
string
Description
Exchange name.
Name
coin
Type
string
Description
Asset ticker (e.g., BTC, ETH).
Name
option_id
Type
string
Description
Option contract identifier.
Name
option_type
Type
string
Description
"call" or "put".
Name
strike
Type
number
Description
Strike price.
Name
expiry_date
Type
string
Description
Expiry date.
Name
direction
Type
string
Description
Trade direction.
Name
amount
Type
number
Description
Trade size in contracts.
Name
price_usd
Type
number
Description
Trade price in USD.
Name
iv_at_trade
Type
number
Description
Implied volatility at time of trade.
Name
traded_at
Type
string
Description
ISO 8601 trade timestamp.

Top volume

Chart: top-volume. Returns the 15 most actively traded contracts.

Name
option_id
Type
string
Description
Option contract identifier.
Name
option_type
Type
string
Description
"call" or "put".
Name
strike
Type
number
Description
Strike price.
Name
expiry_date
Type
string
Description
Expiry date.
Name
volume_24h_usd
Type
number
Description
24-hour volume in USD.
Name
exchange
Type
string
Description
Exchange name.

{
  "data": {
    "chart": "iv-term-structure",
    "coin": "BTC",
    "timeframe": "3M",
    "data": [
      {
        "exchange": "Deribit",
        "coin": "BTC",
        "expiry_date": "2026-04-04",
        "days_to_expiry": 7,
        "atm_iv": 0.45,
        "forward_iv": 0.47,
        "skew_25d": -0.03,
        "rr25": -0.012,
        "bf25": 0.018,
        "total_oi_usd": 890000000,
        "put_oi_usd": 340000000,
        "call_oi_usd": 550000000,
        "total_volume_usd": 125000000,
        "put_volume_usd": 48000000,
        "call_volume_usd": 77000000,
        "put_call_ratio": 0.62,
        "underlying_price": 87200,
        "fetched_at": "2026-03-28T11:50:00Z"
      },
      {
        "exchange": "Deribit",
        "coin": "BTC",
        "expiry_date": "2026-06-26",
        "days_to_expiry": 90,
        "atm_iv": 0.52,
        "forward_iv": 0.54,
        "skew_25d": -0.05,
        "rr25": -0.021,
        "bf25": 0.027,
        "total_oi_usd": 2340000000,
        "put_oi_usd": 980000000,
        "call_oi_usd": 1360000000,
        "total_volume_usd": 67000000,
        "put_volume_usd": 28000000,
        "call_volume_usd": 39000000,
        "put_call_ratio": 0.72,
        "underlying_price": 87200,
        "fetched_at": "2026-03-28T11:50:00Z"
      }
    ],
    "coverage": {
      "availableSince": null,
      "availableTimeframes": []
    },
    "source": "supabase"
  },
  "meta": {
    "request_id": "req_jkl012mno345pqrs",
    "timestamp": "2026-03-28T12:00:00Z"
  }
}

{
  "data": {
    "chart": "oi-by-strike",
    "coin": "BTC",
    "timeframe": "3M",
    "data": [
      {
        "strike": 80000,
        "call_oi_usd": 45000000,
        "put_oi_usd": 120000000
      },
      {
        "strike": 90000,
        "call_oi_usd": 230000000,
        "put_oi_usd": 85000000
      },
      {
        "strike": 100000,
        "call_oi_usd": 340000000,
        "put_oi_usd": 42000000
      }
    ],
    "coverage": {
      "availableSince": null,
      "availableTimeframes": []
    },
    "source": "supabase"
  },
  "meta": {
    "request_id": "req_mno345pqr678stuv",
    "timestamp": "2026-03-28T12:00:00Z"
  }
}

Exchange volume

Time-series of aggregated volume per exchange. Respects the timeframe parameter and supports exchange filtering.

Name
exchange
Type
string
Description
Exchange name.
Name
total_volume_usd
Type
number
Description
Total options volume in USD for this exchange at this timestamp.
Name
fetched_at
Type
string
Description
ISO 8601 timestamp.

Request

GET

/v1/options/data?chart=exchange-volume

curl -G https://www.sharpe.ai/api/v1/options/data \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -d chart=exchange-volume \
  -d coin=BTC \
  -d timeframe=1M

{
  "data": {
    "chart": "exchange-volume",
    "coin": "BTC",
    "timeframe": "1M",
    "data": [
      {
        "exchange": "Deribit",
        "total_volume_usd": 1450000000,
        "fetched_at": "2026-03-01T00:00:00Z"
      }
    ],
    "coverage": {
      "availableSince": "2025-06-01T00:00:00Z",
      "availableTimeframes": ["1W", "1M", "3M", "6M"]
    },
    "source": "supabase"
  },
  "meta": {
    "request_id": "req_pqr678stu901vwxy",
    "timestamp": "2026-03-28T12:00:00Z"
  }
}

Read the error reference