volatility / wire operation
Fit an implied-vol surface
totalfinance.volatility.surface
Fit an implied-volatility surface from chain quotes (IV given directly, or implied from price) and return the surface rows, per-expiry ATM term structure, and the static-arbitrage report (calendar/butterfly violations). The surface never fabricates: non-convergence and extrapolation are reported in diagnostics/warnings.
| Pack / profiles | volatility / default, full, options, strategies |
|---|---|
| Default discovery | Included |
| Required capabilities | None |
| Effects / authorization | none / none |
| Cost / cancellation | small / Do not assume inline interruption |
| Handle-eligible inputs | None |
| Idempotency | not-applicable |
Input schema
{
"type": "object",
"properties": {
"chain": {
"type": "array",
"items": {
"type": "object",
"properties": {
"strike": {
"type": "number",
"exclusiveMinimum": 0
},
"expiry": {
"type": "string",
"description": "ISO date YYYY-MM-DD"
},
"type": {
"type": "string",
"enum": [
"call",
"put"
]
},
"impliedVolatility": {
"type": "number",
"exclusiveMinimum": 0,
"description": "Implied volatility (decimal, e.g. 0.22)"
},
"price": {
"type": "number",
"exclusiveMinimum": 0,
"description": "Option mid price (used to imply IV when `impliedVolatility` omitted)"
}
},
"additionalProperties": false,
"required": [
"strike",
"expiry",
"type"
]
},
"description": "Chain quotes: one row per contract"
},
"spot": {
"type": "number",
"exclusiveMinimum": 0
},
"riskFreeRate": {
"type": "number",
"description": "Continuously-compounded risk-free rate (decimal)"
},
"asOf": {
"anyOf": [
{
"type": "number"
},
{
"type": "string"
}
],
"description": "Valuation instant — epoch ms or a zoned ISO datetime such as \"2026-07-20T10:30:00-04:00\". A bare YYYY-MM-DD is refused: a same-day option's value depends on the time of day. For an end-of-day mark use the 16:00 ET close (13:00 ET on early-close days)."
},
"dividendYield": {
"type": "number",
"description": "Continuous dividend yield (decimal)"
},
"model": {
"type": "string",
"enum": [
"interpolated",
"raw",
"smoothed",
"svi",
"sabr"
],
"description": "Surface model (default interpolated PCHIP; svi/sabr fit parametric smiles)"
},
"underlying": {
"type": "string",
"description": "Ticker of the chain — REQUIRED, it names every contract"
},
"style": {
"type": "string",
"enum": [
"american",
"european"
],
"description": "Exercise style of every contract in the chain — REQUIRED (listed US equity options are 'american'); the library never defaults it"
}
},
"additionalProperties": false,
"required": [
"chain",
"spot",
"riskFreeRate",
"asOf",
"underlying",
"style"
]
}Output schema
{
"type": "object",
"properties": {
"rows": {
"type": "array",
"description": "Surface grid rows (expiry × strike × impliedVolatility)"
},
"expiries": {
"type": "array",
"items": {
"type": "string"
}
},
"arbitrage": {
"type": "object",
"description": "Static-arbitrage report (violations list)"
},
"assumptions": {
"type": "object"
},
"diagnostics": {
"type": "object"
}
},
"required": [
"rows",
"expiries",
"arbitrage",
"assumptions",
"diagnostics"
]
}