Options · Volatility
Options volatility surface parameters
/v1/options/volatility/surface/parametersoptionsVolatilitySurfaceParametersFor each expiration, a smile fitted to the quoted volatilities with five parameters (raw SVI: total variance = a + b (rho (k - m) + sqrt((k - m)^2 + sigma^2)) with k the log-moneyness ln(strike / forward)), the root mean square fit error in volatility points, whether the fit admits no butterfly arbitrage, and the strikes whose volatility is furthest above (rich) and below (cheap) the fitted smile. difference is the quoted volatility minus the fitted one, as a decimal. The fit is a model of the smile, not an observation. An expiration with fewer than five usable strikes is listed without parameters.
Example request
curl -sS --get "https://api.ordermap.si/v1/options/volatility/surface/parameters" \
-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/surface/parameters?${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
5 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. |
max_queryoptional | integerdefault 4min 1max 8 | Number of expirations, nearest first, with at least one day to run. |
topqueryoptional | integerdefault 10min 1max 25 | Strikes listed as rich and as cheap per expiration. |
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
dataarray<object>required22 fields insidebutterfly_arbitrage_freeboolean | nullrequiredThe fitted smile admits no static butterfly arbitrage.cheaparray<object>requiredStrikes furthest below the fit, largest first.4 fields insidedifferencenumberrequirediv minus fitted_iv.fitted_ivnumberrequiredVolatility of the fitted smile.ivnumberrequiredQuoted implied volatility.strikenumberrequiredStrike.
date_of_expirystringdaterequiredExpiration.dteintegerrequiredCalendar days from the trading date.fit_errornumber | nullrequiredRoot mean square error against the quoted volatilities, in volatility points.forwardnumber | nullrequiredForward price implied by the chain.parametersobject | nullrequiredRaw SVI parameters of the total variance against the log-moneyness.5 fields insideanumberrequiredLevel.bnumberrequiredAngle between the wings.mnumberrequiredHorizontal shift of the vertex.rhonumberrequiredSkew, -1 to 1.sigmanumberrequiredSmoothness of the vertex.
richarray<object>requiredStrikes furthest above the fit, largest first.4 fields insidedifferencenumberrequirediv minus fitted_iv.fitted_ivnumberrequiredVolatility of the fitted smile.ivnumberrequiredQuoted implied volatility.strikenumberrequiredStrike.
strikes_usedintegerrequiredStrikes with a usable volatility.
metaobjectrequiredMeta object
Example response
{
"data": [
{
"butterfly_arbitrage_free": true,
"cheap": [
{
"difference": -0.003,
"fitted_iv": 0.165,
"iv": 0.162,
"strike": 5900
}
],
"date_of_expiry": "2026-10-23",
"dte": 7,
"fit_error": 0.18,
"forward": 6026.3,
"parameters": {
"a": 0.0004,
"b": 0.012,
"m": 0.004,
"rho": -0.62,
"sigma": 0.03
},
"rich": [
{
"difference": 0.004,
"fitted_iv": 0.147,
"iv": 0.151,
"strike": 6100
}
],
"strikes_used": 118
}
],
"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.
