Options · Volatility
Options volatility implied distribution
/v1/options/volatility/implied-distributionoptionsVolatilityImpliedDistributionThe 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=SPXWconst params = new URLSearchParams({
underlying_symbol: "SPXW",
});
const res = await fetch(`https://api.ordermap.si/v1/options/volatility/implied-distribution?${params}`, {
headers: { Authorization: `Bearer ${process.env.ORDERMAP_API_KEY}` },
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const { data, meta } = await res.json();
console.log(data, meta.coverage);Set ORDERMAP_API_KEY to your key. Replace the dates with a recent trading date.
Parameters
6 parameters, 1 required.
| Parameter | Type and limits | Description |
|---|---|---|
underlying_queryrequired | stringat 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 ... |
datequeryoptional | stringdate | Trading date (YYYY-MM-DD). Default: the current session, else the most recent completed one. |
sessionqueryoptional | stringrthgthdefault rth | Trading 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_queryoptional | stringdate | The expiration. Default: the nearest with at least one day to run. |
levelsqueryoptional | array<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. |
pointsqueryoptional | integerdefault 101min 21max 201 | Prices of the density grid. |
Response
| Status | Meaning | Body |
|---|---|---|
200 | Successful response. | Schema below |
400 | Invalid, unknown or repeated parameters, or an invalid cursor. | Error object |
401 | Missing or invalid API key. | Error object |
403 | The plan, dataset release or account state does not allow this request. | Error object |
422 | The request is valid but no data exists for it. | Error object |
429 | Rate limit, burst limit or cooldown; wait Retry-After seconds.Retry-After | Error object |
500 | Internal error. | Error object |
503 | Data temporarily unavailable; retry after Retry-After seconds.Retry-After | Error object |
504 | The 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 insideatm_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 insidecumulativearray<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.fittedinterpolatednullpercentilesobjectrequiredPrices at fixed cumulative probabilities.7 fields insidep10number | 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 insideabovenumber | nullrequiredProbability of finishing above.belownumber | nullrequiredProbability of finishing at or below.levelnumberrequiredPrice.
qualityobjectrequiredHow far to trust the distribution.3 fields insideclipped_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.rthgthcurballskewnessnumber | 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 insidechain_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.
