Skip to content

Options · Volatility

Options volatility implied distribution

Price distribution implied by an expiration's smile: density, percentiles, moments and probabilities above and below levels.
On this page

The distribution of the underlying's price at expiration that the option prices of one expiration imply: the density and cumulative probability on a grid of prices, the 5th to 95th percentiles, the mean, standard deviation, skewness and excess kurtosis, and the probability of finishing above and below any levels you give. The grid spans about four standard deviations either side of the forward, so a level outside it reports a probability of exactly 0 or 1 (the density there is not computed). It is implied by option prices: a risk-neutral distribution (the forward measure), not a forecast and not the real-world probability of anything. The smile is fitted with a five-parameter curve when the fit error is under 1.5 volatility points (method fitted); otherwise it is interpolated in total variance between the quoted strikes (method interpolated). Negative second differences of the call price are floored at zero and reported as quality.clipped_mass. Volatilities come from the platform's option chain, solved by the platform.

Example request

curl -sS --get "https://api.ordermap.si/v1/options/volatility/implied-distribution" \
  -H "Authorization: Bearer $ORDERMAP_API_KEY" \
  --data-urlencode underlying_symbol=SPXW

Set ORDERMAP_API_KEY to your key. Replace the dates with a recent trading date.

Parameters

6 parameters, 1 required.

ParameterType and limitsDescription
underlying_symbolqueryrequiredstringat most 8 characterspattern ^[A-Za-z][A-Za-z0-9.]{0,7}$Option root or family: SPX covers the SPX and SPXW roots, SPXW only the weekly root, QQQ, NDXP, RUTW, XSP ...
datequeryoptionalstringdateTrading date (YYYY-MM-DD). Default: the current session, else the most recent completed one.
sessionqueryoptionalstringrthgthdefault rthTrading session: rth is the regular session, gth the overnight (global trading hours) session before the trading date. Overnight data requires the Pro plan and exists only for underlyings with an overnight session; GET /v1/options/sessions shows which.
date_of_expiryqueryoptionalstringdateThe expiration. Default: the nearest with at least one day to run.
levelsqueryoptionalarray<string>comma-separated in one parameter1 to 10 itemseach at most 128 characterspattern ^[0-9]+(\.[0-9]+)?$Prices to give the probability of finishing above and below, comma separated, at most 10.
pointsqueryoptionalintegerdefault 101min 21max 201Prices of the density grid.

Response

StatusMeaningBody
200Successful response.Schema below
400Invalid, unknown or repeated parameters, or an invalid cursor.Error object
401Missing or invalid API key.Error object
403The plan, dataset release or account state does not allow this request.Error object
422The request is valid but no data exists for it.Error object
429Rate limit, burst limit or cooldown; wait Retry-After seconds.Retry-AfterError object
500Internal error.Error object
503Data temporarily unavailable; retry after Retry-After seconds.Retry-AfterError object
504The request timed out.Error object

Authenticated responses carry the X-RateLimit-* headers (see rate limits); 429 and 503 add Retry-After.

200 response body

  • dataobjectrequiredImplied price distribution.41 fields inside
    • atm_ivnumber | nullrequiredAt-the-money implied volatility.
    • date_of_expirystring | nulldaterequiredThe expiration.
    • days_to_expiryinteger | nullrequiredCalendar days from the trading date.
    • excess_kurtosisnumber | nullrequiredExcess kurtosis of the price.
    • forwardnumber | nullrequiredForward price implied by the chain.
    • gridobjectrequiredThe distribution on a uniform price grid.3 fields inside
      • cumulativearray<number>requiredCumulative probability, 0 to 1.
      • densityarray<number>requiredProbability density per unit of price.
      • pricesarray<number>requiredPrices, ascending.
    • meannumber | nullrequiredMean price.
    • methodstring | nullrequiredfitted: a five-parameter smile fitted within 1.5 volatility points; interpolated: total variance interpolated between quoted strikes.fittedinterpolatednull
    • percentilesobjectrequiredPrices at fixed cumulative probabilities.7 fields inside
      • p10number | nullrequiredPrice at the cumulative probability 10%.
      • p25number | nullrequiredPrice at the cumulative probability 25%.
      • p5number | nullrequiredPrice at the cumulative probability 5%.
      • p50number | nullrequiredPrice at the cumulative probability 50%.
      • p75number | nullrequiredPrice at the cumulative probability 75%.
      • p90number | nullrequiredPrice at the cumulative probability 90%.
      • p95number | nullrequiredPrice at the cumulative probability 95%.
    • probabilitiesarray<object>requiredOne entry per level asked.3 fields inside
      • abovenumber | nullrequiredProbability of finishing above.
      • belownumber | nullrequiredProbability of finishing at or below.
      • levelnumberrequiredPrice.
    • qualityobjectrequiredHow far to trust the distribution.3 fields inside
      • clipped_massnumber | nullrequiredProbability mass removed by flooring negative densities at zero.
      • fit_errornumber | nullrequiredRoot mean square error of the fitted smile against the quoted volatilities, in volatility points; null when no fit was possible.
      • strikes_usedintegerrequiredStrikes with a usable volatility.
    • rootsarray<string>requiredOption roots included.
    • sessionstringrequiredSession valued.rthgthcurball
    • skewnessnumber | nullrequiredSkewness of the price.
    • std_devnumber | nullrequiredStandard deviation of the price.
    • trading_datestringdaterequiredTrading date valued.
    • underlying_symbolstringrequiredThe requested underlying.
    • valuationobjectrequiredWhat the snapshot was valued on.7 fields inside
      • chain_timestampinteger | nullunix-msrequiredTime of the option chain the valuation used. Unix epoch milliseconds (UTC).
      • open_interest_datestring | nulldaterequiredDate of the open interest the positioning is based on.
      • risk_free_ratenumber | nullrequiredContinuously compounded risk-free rate used.
      • timestampinteger | nullunix-msrequiredValuation time. Unix epoch milliseconds (UTC).
      • underlying_pricenumber | nullrequiredUnderlying price used.
      • underlying_stalebooleanrequiredThe underlying price is older than the freshness limit.
      • underlying_timestampinteger | nullunix-msrequiredTime of the underlying price. Unix epoch milliseconds (UTC).
  • metaobjectrequiredMeta object

Example response

{
  "data": {
    "atm_iv": 0.152,
    "date_of_expiry": "2026-10-23",
    "days_to_expiry": 7,
    "excess_kurtosis": 0.42,
    "forward": 6026.3,
    "grid": {
      "cumulative": [
        0.0004,
        0.01,
        0.06
      ],
      "density": [
        0.00012,
        0.0007,
        0.0021
      ],
      "prices": [
        5700,
        5800,
        5900
      ]
    },
    "mean": 6026.3,
    "method": "fitted",
    "percentiles": {
      "p10": 5905.4,
      "p25": 5966.2,
      "p5": 5870.1,
      "p50": 6024.3,
      "p75": 6083.5,
      "p90": 6137.2,
      "p95": 6166.8
    },
    "probabilities": [
      {
        "above": 0.55,
        "below": 0.45,
        "level": 6000
      }
    ],
    "quality": {
      "clipped_mass": 0,
      "fit_error": 0.21,
      "strikes_used": 118
    },
    "roots": [
      "SPX",
      "SPXW"
    ],
    "session": "rth",
    "skewness": -0.31,
    "std_dev": 91.2,
    "trading_date": "2026-10-16",
    "underlying_symbol": "SPX",
    "valuation": {
      "chain_timestamp": 1792160995000,
      "open_interest_date": "2026-10-15",
      "risk_free_rate": 0.0412,
      "timestamp": 1792161000000,
      "underlying_price": 6021.4,
      "underlying_stale": false,
      "underlying_timestamp": 1792160999000
    }
  },
  "meta": {
    "as_of": 1760659200123,
    "coverage": {
      "complete": true
    },
    "delay_ms": 0,
    "delayed": false,
    "request_id": "0199f0c2-5a1e-7c3b-9d4e-2b6f8a1c3d5e",
    "source": "opra"
  }
}

Values are illustrative. Missing values are null, never 0.