{"openapi":"3.1.0","info":{"title":"Derivatives Pricer","description":"x402-paid Black-Scholes European option pricing, Greeks, IV surfaces, price/scenario on submitted smiles (TV bilinear), portfolio risk, free demo, and MCP. USDC exact on Solana (PayAI) and/or Base (CDP when configured). Receive wallets appear only in HTTP 402, never on free discovery.","version":"1.6.0","contact":{"name":"Derivatives Pricer","url":"https://derivatives-pricer-production.up.railway.app"}},"servers":[{"url":"https://derivatives-pricer-production.up.railway.app","description":"Production"}],"tags":[{"name":"options","description":"Single-contract European option pricing and IV"},{"name":"volatility","description":"Implied volatility surface from market premiums"},{"name":"surface","description":"Price and scenario reval on a submitted IV surface (log-moneyness total-variance bilinear)"},{"name":"portfolio","description":"Multi-leg portfolio Greeks and scenario analysis"},{"name":"discovery","description":"Free service discovery endpoints"}],"paths":{"/":{"get":{"operationId":"getServiceCard","tags":["discovery"],"summary":"Service card for agents","description":"Machine-readable catalog: capabilities, endpoints, examples, settlement. Free — no payment required.","security":[],"x-free":true,"responses":{"200":{"description":"Service discovery document","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/health":{"get":{"operationId":"getHealth","tags":["discovery"],"summary":"Liveness probe","description":"Returns service status, networks, facilitator labels, and pricing. Free — no wallets, no payment required.","security":[],"x-free":true,"responses":{"200":{"description":"Service is healthy","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/openapi.json":{"get":{"operationId":"getOpenApi","tags":["discovery"],"summary":"OpenAPI 3.1 specification","description":"Full OpenAPI document for this service. Free — no payment required.","security":[],"x-free":true,"responses":{"200":{"description":"OpenAPI 3.1 document","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/llms.txt":{"get":{"operationId":"getLlmsTxt","tags":["discovery"],"summary":"llms.txt agent discovery document","description":"Concise Markdown summary for AI agents (llms.txt convention): capabilities, paid endpoints, discovery links. Free — no payment required.","security":[],"x-free":true,"responses":{"200":{"description":"llms.txt Markdown as text/plain","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/v1/demo/option-price":{"get":{"operationId":"getDemoOptionPrice","tags":["discovery"],"summary":"Free fixed ATM option sample","description":"Returns a fixed ATM European call priced with the live BSM engine. No payment. Abuse-resistant (inputs not customizable). Free — security: [].","security":[],"x-free":true,"responses":{"200":{"description":"Demo price + Greeks","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"post":{"operationId":"postDemoOptionPrice","tags":["discovery"],"summary":"Free fixed ATM option sample (POST alias)","description":"Same as GET /v1/demo/option-price. Body ignored. Free.","security":[],"x-free":true,"responses":{"200":{"description":"Demo price + Greeks","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/mcp":{"post":{"operationId":"mcpStreamableHttp","tags":["discovery"],"summary":"MCP Streamable HTTP (stateless)","description":"Model Context Protocol endpoint. Tools: service_info (free), price_option and implied_vol_surface (USDC x402 may be required). Not an HTTP 402 REST resource — payment is handled inside MCP meta via @x402/mcp.","security":[],"x-free":true,"responses":{"200":{"description":"MCP JSON-RPC / streamable HTTP response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/.well-known/x402":{"get":{"operationId":"getWellKnownX402","tags":["discovery"],"summary":"x402 well-known discovery manifest","description":"Machine-readable x402 discovery (resources, pricing, settlement). Free — no payment required. Same payload as /.well-known/x402.json.","security":[],"x-free":true,"responses":{"200":{"description":"x402 discovery document","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/.well-known/x402.json":{"get":{"operationId":"getWellKnownX402Json","tags":["discovery"],"summary":"x402 well-known discovery manifest","description":"Machine-readable x402 discovery (JSON alias). Free — no payment required.","security":[],"x-free":true,"responses":{"200":{"description":"x402 discovery document","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/v1/option/price":{"post":{"operationId":"priceOption","tags":["options"],"summary":"Price European option + Greeks","description":"Black-Scholes-Merton fair value and full analytic Greeks (delta, gamma, vega, theta, rho). Paid via x402: $0.01 USDC per request (Solana mainnet or Base mainnet).","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","format":"uuid"},"description":"Optional key for safe retries of a paid request"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionPriceRequest"},"example":{"spot":100,"strike":100,"timeToExpiry":1,"rate":0.05,"volatility":0.2,"optionType":"call","dividendYield":0}}}},"responses":{"200":{"description":"Option price and Greeks (after successful x402 settlement)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionPriceResponse"},"example":{"price":10.45057562,"greeks":{"delta":0.63683059,"gamma":0.01876202,"vega":37.52403469,"theta":-6.41402764,"rho":53.23248343},"inputs":{"spot":100,"strike":100,"timeToExpiry":1,"rate":0.05,"volatility":0.2,"optionType":"call","dividendYield":0},"model":"black-scholes-merton","units":{"price":"option value in spot currency units","delta":"dV/dS (share equivalent)","gamma":"d²V/dS²","vega":"dV/dσ per 1.0 absolute volatility (not per 1%)","theta":"dV/dT per year (not per day)","rho":"dV/dr per 1.0 absolute rate (not per 1%)"},"requestId":"00000000-0000-4000-8000-000000000001","computedAt":"2026-01-01T00:00:00.000Z"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Payment required (x402). Decode PAYMENT-REQUIRED header (base64 JSON) for accepts[] — Solana mainnet and/or Base mainnet USDC exact, amount, and payTo.","headers":{"PAYMENT-REQUIRED":{"description":"Base64-encoded x402 payment requirements (v2)","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequiredBody"}}}}},"x-pricing":{"currency":"USDC","price_usd":0.01,"unit":"request","scheme":"exact","networks":["solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp","eip155:8453"]},"security":[{"x402":[]}]}},"/v1/option/implied-vol":{"post":{"operationId":"solveImpliedVol","tags":["options"],"summary":"Implied volatility from market premium","description":"Solve Black-Scholes implied volatility from a single market premium and return full analytic Greeks at the solved σ. Paid via x402: $0.03 USDC per request (Solana mainnet or Base mainnet).","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","format":"uuid"},"description":"Optional key for safe retries of a paid request"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImpliedVolRequest"},"example":{"underlying":100,"strike":100,"timeToExpiry":1,"rate":0.05,"dividendYield":0,"optionType":"call","premium":10.45057562}}}},"responses":{"200":{"description":"Implied vol, Greeks, model price (after successful x402 settlement)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImpliedVolResponse"},"example":{"impliedVol":0.2,"greeks":{"delta":0.63683059,"gamma":0.01876202,"vega":37.52403469,"theta":-6.41402764,"rho":53.23248343},"modelPrice":10.45057562,"priceError":0,"iterations":12,"converged":true,"inputs":{"underlying":100,"strike":100,"timeToExpiry":1,"rate":0.05,"dividendYield":0,"optionType":"call","premium":10.45057562},"requestId":"00000000-0000-4000-8000-000000000003","computedAt":"2026-01-01T00:00:00.000Z"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Payment required (x402). Decode PAYMENT-REQUIRED header (base64 JSON) for accepts[] — Solana mainnet and/or Base mainnet USDC exact, amount, and payTo.","headers":{"PAYMENT-REQUIRED":{"description":"Base64-encoded x402 payment requirements (v2)","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequiredBody"}}}},"422":{"description":"IV solver failed to converge or premium out of bounds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-pricing":{"currency":"USDC","price_usd":0.03,"unit":"request","scheme":"exact","networks":["solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp","eip155:8453"]},"security":[{"x402":[]}]}},"/v1/volatility/surface":{"post":{"operationId":"buildVolatilitySurface","tags":["volatility"],"summary":"Implied volatility surface from market premiums","description":"Invert a market option book into an IV surface grid, per-quote IV and Greeks, fit metrics, and solve stats. Shared rate/yield; each option has its own underlying (multi-maturity marks). Paid via x402: $0.10 USDC per request (Solana mainnet or Base mainnet).","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","format":"uuid"},"description":"Optional key for safe retries of a paid request"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VolatilitySurfaceRequest"},"example":{"rate":0.05,"dividendYield":0,"options":[{"underlying":100,"strike":90,"timeToExpiry":0.25,"optionType":"call","premium":12.21003823},{"underlying":102,"strike":100,"timeToExpiry":0.5,"optionType":"call","premium":8.67399132},{"underlying":101,"strike":110,"timeToExpiry":1,"optionType":"put","premium":10.13483934}]}}}},"responses":{"200":{"description":"IV surface, points, fit, and stats (after successful x402 settlement)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VolatilitySurfaceResponse"},"example":{"surface":{"strikes":[90,100,110],"maturities":[0.25,0.5,1],"impliedVols":[[0.25,null,null],[null,0.22,null],[null,null,0.2]]},"market":{"rate":0.05,"dividendYield":0},"points":[{"index":0,"underlying":100,"strike":90,"timeToExpiry":0.25,"optionType":"call","premium":12.21003823,"impliedVol":0.25,"greeks":{"delta":0.84264403,"gamma":0.01925343,"vega":12.03339684,"theta":-9.61941667,"rho":18.01359123},"modelPrice":12.21003824,"priceError":1e-8,"status":"ok"},{"index":1,"underlying":102,"strike":100,"timeToExpiry":0.5,"optionType":"call","premium":8.67399132,"impliedVol":0.22,"greeks":{"delta":0.64273679,"gamma":0.02351518,"vega":26.91171634,"theta":-8.76483566,"rho":28.44258072},"modelPrice":8.67399129,"priceError":-3e-8,"status":"ok"},{"index":2,"underlying":101,"strike":110,"timeToExpiry":1,"optionType":"put","premium":10.13483934,"impliedVol":0.2,"greeks":{"delta":-0.53060844,"gamma":0.01969146,"vega":40.17451831,"theta":-0.83113722,"rho":-63.72629213},"modelPrice":10.13483936,"priceError":2e-8,"status":"ok"}],"fit":{"okCount":3,"failedCount":0,"meanAbsPriceError":2e-8,"maxAbsPriceError":3e-8,"rmsePriceError":2e-8},"stats":{"optionCount":3,"elapsedMs":2.5,"solver":"fastImpliedVol","avgIterations":12.3333},"requestId":"00000000-0000-4000-8000-000000000002","computedAt":"2026-01-01T00:00:00.000Z"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Payment required (x402). Decode PAYMENT-REQUIRED header (base64 JSON) for accepts[] — Solana mainnet and/or Base mainnet USDC exact, amount, and payTo.","headers":{"PAYMENT-REQUIRED":{"description":"Base64-encoded x402 payment requirements (v2)","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequiredBody"}}}}},"x-pricing":{"currency":"USDC","price_usd":0.1,"unit":"request","scheme":"exact","networks":["solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp","eip155:8453"]},"security":[{"x402":[]}]}},"/v1/portfolio/greeks":{"post":{"operationId":"portfolioGreeks","tags":["portfolio"],"summary":"Net portfolio Greeks and MTM","description":"Aggregate net Greeks and mark-to-model for a multi-leg European option book. quantity > 0 long, quantity < 0 short. Optional dollar Greeks. Paid via x402: $0.15 USDC per request (Solana mainnet or Base mainnet).","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","format":"uuid"},"description":"Optional key for safe retries of a paid request"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortfolioGreeksRequest"},"example":{"rate":0.05,"dividendYield":0,"includeDollarGreeks":true,"positions":[{"underlying":100,"strike":100,"timeToExpiry":1,"optionType":"call","quantity":10,"volatility":0.2},{"underlying":100,"strike":110,"timeToExpiry":1,"optionType":"put","quantity":-5,"volatility":0.22}]}}}},"responses":{"200":{"description":"Net MTM, Greeks, per-leg detail (after successful x402 settlement)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortfolioGreeksResponse"},"example":{"net":{"mtm":47.16439511,"greeks":{"delta":9.05941615,"gamma":0.09736793,"vega":176.68540458,"theta":-58.62185203,"rho":858.77721991},"dollarGreeks":{"deltaCash":905.941615,"gammaCash":486.8396,"vegaPerPoint":1.76685405,"thetaPerDay":-0.16060781,"rhoPerPoint":8.5877722}},"legs":[{"index":0,"quantity":10,"underlying":100,"strike":100,"timeToExpiry":1,"optionType":"call","volatility":0.2,"price":10.45057562,"contribution":104.50575619,"greeks":{"delta":6.3683059,"gamma":0.18762017,"vega":375.24034692,"theta":-64.1402764,"rho":532.32483426}},{"index":1,"quantity":-5,"underlying":100,"strike":110,"timeToExpiry":1,"optionType":"put","volatility":0.22,"price":11.46827222,"contribution":-57.34136108,"greeks":{"delta":2.69111025,"gamma":-0.09025225,"vega":-198.55494233,"theta":5.51842437,"rho":326.45238565}}],"positionCount":2,"requestId":"00000000-0000-4000-8000-000000000004","computedAt":"2026-01-01T00:00:00.000Z"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Payment required (x402). Decode PAYMENT-REQUIRED header (base64 JSON) for accepts[] — Solana mainnet and/or Base mainnet USDC exact, amount, and payTo.","headers":{"PAYMENT-REQUIRED":{"description":"Base64-encoded x402 payment requirements (v2)","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequiredBody"}}}}},"x-pricing":{"currency":"USDC","price_usd":0.15,"unit":"request","scheme":"exact","networks":["solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp","eip155:8453"]},"security":[{"x402":[]}]}},"/v1/portfolio/scenario":{"post":{"operationId":"portfolioScenario","tags":["portfolio"],"summary":"Portfolio scenario reprice","description":"Reprice a multi-leg European portfolio under relative spot/vol shocks and calendar time decay. Returns base MTM+Greeks and per-scenario shocked MTM, MTM change, and full Greeks. Paid via x402: $0.25 USDC per request (Solana mainnet or Base mainnet).","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","format":"uuid"},"description":"Optional key for safe retries of a paid request"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortfolioScenarioRequest"},"example":{"rate":0.05,"dividendYield":0,"positions":[{"underlying":100,"strike":100,"timeToExpiry":1,"optionType":"call","quantity":10,"volatility":0.2},{"underlying":100,"strike":110,"timeToExpiry":1,"optionType":"put","quantity":-5,"volatility":0.22}],"scenarios":[{"name":"spot_down_10","spotShock":-0.1,"volShock":0,"timeDecayDays":0},{"name":"vol_up_20pct_rel","spotShock":0,"volShock":0.2,"timeDecayDays":1}]}}}},"responses":{"200":{"description":"Base and shocked portfolio MTM/Greeks (after successful x402 settlement)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortfolioScenarioResponse"},"example":{"base":{"mtm":47.16439511,"greeks":{"delta":9.05941615,"gamma":0.09736793,"vega":176.68540458,"theta":-58.62185203,"rho":858.77721991}},"scenarios":[{"name":"spot_down_10","shocks":{"spotShock":-0.1,"volShock":0,"timeDecayDays":0},"mtm":-37.85755566,"mtmChange":-85.02195077,"greeks":{"delta":7.8848641,"gamma":0.13279827,"vega":201.29852574,"theta":-55.98280497,"rho":747.49532487}},{"name":"vol_up_20pct_rel","shocks":{"spotShock":0,"volShock":0.2,"timeDecayDays":1},"mtm":53.31386329,"mtmChange":6.14946818,"greeks":{"delta":8.86589449,"gamma":0.08214409,"vega":178.51169933,"theta":-60.74906514,"rho":830.99263852}}],"positionCount":2,"scenarioCount":2,"requestId":"00000000-0000-4000-8000-000000000005","computedAt":"2026-01-01T00:00:00.000Z"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Payment required (x402). Decode PAYMENT-REQUIRED header (base64 JSON) for accepts[] — Solana mainnet and/or Base mainnet USDC exact, amount, and payTo.","headers":{"PAYMENT-REQUIRED":{"description":"Base64-encoded x402 payment requirements (v2)","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequiredBody"}}}}},"x-pricing":{"currency":"USDC","price_usd":0.25,"unit":"request","scheme":"exact","networks":["solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp","eip155:8453"]},"security":[{"x402":[]}]}},"/v1/option/price-from-surface":{"post":{"operationId":"priceFromSurface","tags":["options","surface"],"summary":"Price options on a submitted IV surface","description":"Price one or more European options on a submitted implied-vol surface. Convention: log_moneyness_forward with k=ln(K/F). Interpolation: total_variance_bilinear (w=σ²T in k,T). wingRule=flat_vol (clamp to edge vol; no wing model). Caps: MAX_SURFACE_POINTS / MAX_SURFACE_PRICE_OPTIONS. Paid via x402: $0.08 USDC per request. Prefer /v1/option/price for scalar σ.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","format":"uuid"},"description":"Optional key for safe retries of a paid request"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceFromSurfaceRequest"},"examples":{"equitySmile":{"summary":"3×3 equity-like smile in (k,T)","value":{"surfaceConvention":"log_moneyness_forward","interpolation":"total_variance_bilinear","wingRule":"flat_vol","rate":0.05,"dividendYield":0,"surface":[{"k":-0.1,"timeToExpiry":0.25,"iv":0.22},{"k":0,"timeToExpiry":0.25,"iv":0.2},{"k":0.1,"timeToExpiry":0.25,"iv":0.23},{"k":-0.1,"timeToExpiry":0.5,"iv":0.21},{"k":0,"timeToExpiry":0.5,"iv":0.2},{"k":0.1,"timeToExpiry":0.5,"iv":0.22},{"k":-0.1,"timeToExpiry":1,"iv":0.205},{"k":0,"timeToExpiry":1,"iv":0.2},{"k":0.1,"timeToExpiry":1,"iv":0.215}],"options":[{"underlying":100,"strike":100,"timeToExpiry":1,"optionType":"call","quantity":1}]}},"commodityForwards":{"summary":"Commodity/power-style strike+underlying points (converted to k server-side)","value":{"surfaceConvention":"log_moneyness_forward","interpolation":"total_variance_bilinear","wingRule":"flat_vol","rate":0.04,"dividendYield":0.02,"surface":[{"strike":45,"underlying":50,"timeToExpiry":0.25,"iv":0.35},{"strike":50,"underlying":50,"timeToExpiry":0.25,"iv":0.3},{"strike":55,"underlying":50,"timeToExpiry":0.25,"iv":0.32},{"strike":45,"underlying":52,"timeToExpiry":0.5,"iv":0.33},{"strike":50,"underlying":52,"timeToExpiry":0.5,"iv":0.28},{"strike":55,"underlying":52,"timeToExpiry":0.5,"iv":0.3}],"options":[{"underlying":50,"strike":50,"timeToExpiry":0.25,"optionType":"call","quantity":1,"id":"pwr-atm-q1"}]}}}}}},"responses":{"200":{"description":"Per-option price, interpolated σ, k, F, BS Greeks (after x402 settlement)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceFromSurfaceResponse"},"example":{"results":[{"index":0,"underlying":100,"strike":100,"timeToExpiry":1,"optionType":"call","quantity":1,"forward":100,"k":0,"impliedVol":0.2,"price":10.45057562,"greeks":{"delta":0.63683059,"gamma":0.01876202,"vega":37.52403469,"theta":-6.41402764,"rho":53.23248343},"contribution":10.45057562}],"book":{"mtm":10.45057562,"greeks":{"delta":0.63683059,"gamma":0.01876202,"vega":37.52403469,"theta":-6.41402764,"rho":53.23248343}},"units":{"price":"option value in spot currency units","delta":"dV/dS (share equivalent) at sticky/interpolated σ","gamma":"d²V/dS²","vega":"dV/dσ per 1.0 absolute volatility (not per 1%)","theta":"dV/dT per year (not per day)","rho":"dV/dr per 1.0 absolute rate (not per 1%)"},"surfaceMeta":{"pointCount":9,"kCount":3,"tCount":3,"convention":"log_moneyness_forward","interpolation":"total_variance_bilinear","wingRule":"flat_vol"},"warnings":[],"model":"black-scholes-merton+surface-tv-bilinear","requestId":"00000000-0000-4000-8000-000000000006","computedAt":"2026-01-01T00:00:00.000Z"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Payment required (x402). Decode PAYMENT-REQUIRED header (base64 JSON) for accepts[] — Solana mainnet and/or Base mainnet USDC exact, amount, and payTo.","headers":{"PAYMENT-REQUIRED":{"description":"Base64-encoded x402 payment requirements (v2)","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequiredBody"}}}}},"x-pricing":{"currency":"USDC","price_usd":0.08,"unit":"request","scheme":"exact","networks":["solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp","eip155:8453"]},"security":[{"x402":[]}]}},"/v1/option/scenario-from-surface":{"post":{"operationId":"scenarioFromSurface","tags":["options","surface","portfolio"],"summary":"Book reval on IV surface with sticky smile shocks","description":"Revalue a book on a submitted IV surface: base vs scenario on the same total-variance bilinear interpolator. Sticky: moneyness (default) | strike | fixed_vol. Shocks: underlyingRel XOR underlyingAbs, rateBp, timeDays, volAbs, volRel, smileTwist (vol points per unit k). Vol order: interpolate → volAbs → volRel → smileTwist*k. Greeks are sticky-σ BS Greeks (NOT full smile bump deltas). Paid via x402: $0.15 USDC. Prefer /v1/portfolio/scenario for scalar-σ books.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","format":"uuid"},"description":"Optional key for safe retries of a paid request"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScenarioFromSurfaceRequest"},"example":{"surfaceConvention":"log_moneyness_forward","interpolation":"total_variance_bilinear","wingRule":"flat_vol","rate":0.05,"dividendYield":0,"surface":[{"k":-0.1,"timeToExpiry":0.25,"iv":0.22},{"k":0,"timeToExpiry":0.25,"iv":0.2},{"k":0.1,"timeToExpiry":0.25,"iv":0.23},{"k":-0.1,"timeToExpiry":0.5,"iv":0.21},{"k":0,"timeToExpiry":0.5,"iv":0.2},{"k":0.1,"timeToExpiry":0.5,"iv":0.22},{"k":-0.1,"timeToExpiry":1,"iv":0.205},{"k":0,"timeToExpiry":1,"iv":0.2},{"k":0.1,"timeToExpiry":1,"iv":0.215}],"sticky":"moneyness","positions":[{"underlying":100,"strike":100,"timeToExpiry":1,"optionType":"call","quantity":1}],"scenario":{"underlyingRel":0.1,"rateBp":0,"timeDays":0,"volAbs":0,"volRel":0,"smileTwist":0}}}}},"responses":{"200":{"description":"Per-leg and book base/scenario values, sticky-σ Greeks, scenario echo, warnings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScenarioFromSurfaceResponse"},"example":{"sticky":"moneyness","scenario":{"underlyingRel":0.1,"rateBp":0,"timeDays":0,"volAbs":0,"volRel":0,"smileTwist":0,"rateScenario":0.05},"legs":[{"index":0,"quantity":1,"optionType":"call","strike":100,"base":{"underlying":100,"timeToExpiry":1,"forward":100,"k":0,"impliedVol":0.2,"price":10.45057562,"greeks":{"delta":0.63683059,"gamma":0.01876202,"vega":37.52403469,"theta":-6.41402764,"rho":53.23248343},"contribution":10.45057562},"scenario":{"underlying":110,"timeToExpiry":1,"forward":110,"k":-0.09531018,"impliedVol":0.20476824,"price":17.8125541,"greeks":{"delta":0.79160899,"gamma":0.01273721,"vega":31.55892407,"theta":-6.69435438,"rho":69.26443492},"contribution":17.8125541},"deltaValue":7.36197848}],"book":{"valueBase":10.45057562,"valueScenario":17.8125541,"deltaValue":7.36197848,"greeksBase":{"delta":0.63683059,"gamma":0.01876202,"vega":37.52403469,"theta":-6.41402764,"rho":53.23248343},"greeksScenario":{"delta":0.79160899,"gamma":0.01273721,"vega":31.55892407,"theta":-6.69435438,"rho":69.26443492},"greeksNote":"Greeks are analytic BS Greeks at sticky/scenario σ — NOT full smile-recalibrated bump deltas"},"surfaceMeta":{"pointCount":9,"kCount":3,"tCount":3,"convention":"log_moneyness_forward"},"warnings":[],"model":"black-scholes-merton+surface-tv-bilinear","requestId":"00000000-0000-4000-8000-000000000007","computedAt":"2026-01-01T00:00:00.000Z"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Payment required (x402). Decode PAYMENT-REQUIRED header (base64 JSON) for accepts[] — Solana mainnet and/or Base mainnet USDC exact, amount, and payTo.","headers":{"PAYMENT-REQUIRED":{"description":"Base64-encoded x402 payment requirements (v2)","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequiredBody"}}}}},"x-pricing":{"currency":"USDC","price_usd":0.15,"unit":"request","scheme":"exact","networks":["solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp","eip155:8453"]},"security":[{"x402":[]}]}}},"components":{"schemas":{"OptionType":{"type":"string","enum":["call","put"],"description":"European call or put"},"Greeks":{"type":"object","description":"Analytic Black-Scholes-Merton Greeks. Vega/theta/rho are raw derivatives (per 1.0 vol, per year, per 1.0 rate).","required":["delta","gamma","vega","theta","rho"],"properties":{"delta":{"type":"number","description":"dV/dS — underlying hedge ratio"},"gamma":{"type":"number","description":"d²V/dS² — convexity"},"vega":{"type":"number","description":"dV/dσ per 1.0 absolute volatility (not per 1%)"},"theta":{"type":"number","description":"dV/dT per year (not per calendar day)"},"rho":{"type":"number","description":"dV/dr per 1.0 absolute rate (not per 1%)"}},"additionalProperties":false},"OptionPriceRequest":{"type":"object","title":"EuropeanOptionPriceRequest","description":"Inputs for Black-Scholes-Merton European option fair value. timeToExpiry is a year-fraction.","required":["spot","strike","timeToExpiry","rate","volatility","optionType"],"additionalProperties":false,"properties":{"spot":{"type":"number","exclusiveMinimum":0,"description":"Underlying price S (> 0)"},"strike":{"type":"number","exclusiveMinimum":0,"description":"Strike price K (> 0)"},"timeToExpiry":{"type":"number","minimum":0,"description":"Time to expiry T in years (≥ 0)"},"rate":{"type":"number","description":"Continuous risk-free rate r (e.g. 0.05 = 5%)"},"volatility":{"type":"number","exclusiveMinimum":0,"description":"Annualized volatility σ as a decimal (e.g. 0.2 = 20%)"},"optionType":{"$ref":"#/components/schemas/OptionType"},"dividendYield":{"type":"number","minimum":0,"default":0,"description":"Continuous dividend/convenience yield q (default 0)"}}},"OptionPriceResponse":{"type":"object","title":"EuropeanOptionPriceResponse","required":["price","greeks","inputs","model","requestId","computedAt"],"properties":{"price":{"type":"number","description":"Model option fair value"},"greeks":{"$ref":"#/components/schemas/Greeks"},"inputs":{"type":"object","description":"Echo of validated inputs","additionalProperties":true},"model":{"type":"string","const":"black-scholes-merton"},"units":{"type":"object","additionalProperties":{"type":"string"}},"requestId":{"type":"string"},"computedAt":{"type":"string","description":"ISO-8601 UTC timestamp"}}},"MarketOptionQuote":{"type":"object","required":["underlying","strike","timeToExpiry","optionType","premium"],"additionalProperties":false,"properties":{"underlying":{"type":"number","exclusiveMinimum":0,"description":"Underlying S for this quote; may differ by maturity"},"strike":{"type":"number","exclusiveMinimum":0},"timeToExpiry":{"type":"number","minimum":0},"optionType":{"$ref":"#/components/schemas/OptionType"},"premium":{"type":"number","minimum":0,"description":"Market option premium"}}},"VolatilitySurfaceRequest":{"type":"object","title":"ImpliedVolatilitySurfaceRequest","description":"Shared rate/yield plus market quotes with per-row underlyings.","required":["rate","options"],"additionalProperties":false,"properties":{"rate":{"type":"number","description":"Shared continuous risk-free rate r"},"dividendYield":{"type":"number","minimum":0,"default":0,"description":"Shared continuous yield q (default 0)"},"options":{"type":"array","minItems":1,"maxItems":200,"items":{"$ref":"#/components/schemas/MarketOptionQuote"}}}},"SurfacePoint":{"type":"object","properties":{"index":{"type":"integer"},"underlying":{"type":"number"},"strike":{"type":"number"},"timeToExpiry":{"type":"number"},"optionType":{"$ref":"#/components/schemas/OptionType"},"premium":{"type":"number"},"impliedVol":{"type":["number","null"]},"greeks":{"oneOf":[{"$ref":"#/components/schemas/Greeks"},{"type":"null"}]},"modelPrice":{"type":["number","null"]},"priceError":{"type":["number","null"],"description":"modelPrice − premium"},"status":{"type":"string","enum":["ok","failed"]},"reason":{"type":"string"}}},"VolatilitySurfaceResponse":{"type":"object","title":"ImpliedVolatilitySurfaceResponse","required":["surface","market","points","fit","stats","requestId","computedAt"],"properties":{"surface":{"type":"object","required":["strikes","maturities","impliedVols"],"properties":{"strikes":{"type":"array","items":{"type":"number"}},"maturities":{"type":"array","items":{"type":"number"}},"impliedVols":{"type":"array","description":"Grid [strikeIndex][maturityIndex]; null if empty","items":{"type":"array","items":{"type":["number","null"]}}}}},"market":{"type":"object","properties":{"rate":{"type":"number"},"dividendYield":{"type":"number"}}},"points":{"type":"array","items":{"$ref":"#/components/schemas/SurfacePoint"}},"fit":{"type":"object","properties":{"okCount":{"type":"integer"},"failedCount":{"type":"integer"},"meanAbsPriceError":{"type":["number","null"]},"maxAbsPriceError":{"type":["number","null"]},"rmsePriceError":{"type":["number","null"]}}},"stats":{"type":"object","properties":{"optionCount":{"type":"integer"},"elapsedMs":{"type":"number"},"solver":{"type":"string","const":"fastImpliedVol"},"avgIterations":{"type":"number"}}},"requestId":{"type":"string"},"computedAt":{"type":"string"}}},"PaymentRequiredBody":{"type":"object","description":"Optional JSON body on unpaid requests (server may also return {}). Primary payment terms are in PAYMENT-REQUIRED.","properties":{"error":{"type":"string","example":"payment_required"},"message":{"type":"string"},"path":{"type":"string"},"method":{"type":"string"}}},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}},"ImpliedVolRequest":{"type":"object","title":"ImpliedVolRequest","description":"Solve Black-Scholes implied volatility from a single market premium.","required":["underlying","strike","timeToExpiry","rate","optionType","premium"],"additionalProperties":false,"properties":{"underlying":{"type":"number","exclusiveMinimum":0,"description":"Underlying price S (> 0)"},"strike":{"type":"number","exclusiveMinimum":0,"description":"Strike K (> 0)"},"timeToExpiry":{"type":"number","minimum":0,"description":"Time to expiry T in years (≥ 0)"},"rate":{"type":"number","description":"Continuous risk-free rate r"},"dividendYield":{"type":"number","minimum":0,"default":0,"description":"Continuous yield q (default 0)"},"optionType":{"$ref":"#/components/schemas/OptionType"},"premium":{"type":"number","minimum":0,"description":"Observed market premium"}}},"ImpliedVolResponse":{"type":"object","title":"ImpliedVolResponse","required":["impliedVol","greeks","modelPrice","priceError","iterations","converged","requestId","computedAt"],"properties":{"impliedVol":{"type":"number","description":"Solved annualized volatility σ"},"greeks":{"$ref":"#/components/schemas/Greeks"},"modelPrice":{"type":"number","description":"BSM price at solved σ"},"priceError":{"type":"number","description":"modelPrice − premium"},"iterations":{"type":"integer"},"converged":{"type":"boolean"},"reason":{"type":"string"},"inputs":{"type":"object","additionalProperties":true},"requestId":{"type":"string"},"computedAt":{"type":"string","description":"ISO-8601 UTC timestamp"}}},"PortfolioPosition":{"type":"object","required":["underlying","strike","timeToExpiry","optionType","quantity","volatility"],"additionalProperties":false,"properties":{"underlying":{"type":"number","exclusiveMinimum":0,"description":"Underlying S for this leg"},"strike":{"type":"number","exclusiveMinimum":0},"timeToExpiry":{"type":"number","minimum":0},"optionType":{"$ref":"#/components/schemas/OptionType"},"quantity":{"type":"number","description":"Position size; >0 long, <0 short; must be non-zero"},"volatility":{"type":"number","exclusiveMinimum":0,"description":"Annualized vol σ for this leg"}}},"DollarGreeks":{"type":"object","properties":{"deltaCash":{"type":"number","description":"Σ delta_i * S_i"},"gammaCash":{"type":"number","description":"Σ 0.5 * gamma_i * S_i²"},"vegaPerPoint":{"type":"number","description":"net vega * 0.01"},"thetaPerDay":{"type":"number","description":"net theta / 365"},"rhoPerPoint":{"type":"number","description":"net rho * 0.01"}}},"PortfolioGreeksRequest":{"type":"object","title":"PortfolioGreeksRequest","description":"Aggregate net Greeks and MTM for a multi-leg European option book.","required":["rate","positions"],"additionalProperties":false,"properties":{"rate":{"type":"number"},"dividendYield":{"type":"number","minimum":0,"default":0},"includeDollarGreeks":{"type":"boolean","default":false,"description":"If true, include cash delta/gamma and per-point vega/theta/rho scalings"},"positions":{"type":"array","minItems":1,"maxItems":100,"items":{"$ref":"#/components/schemas/PortfolioPosition"}}}},"PortfolioGreeksResponse":{"type":"object","title":"PortfolioGreeksResponse","required":["net","legs","positionCount","requestId","computedAt"],"properties":{"net":{"type":"object","required":["mtm","greeks"],"properties":{"mtm":{"type":"number"},"greeks":{"$ref":"#/components/schemas/Greeks"},"dollarGreeks":{"$ref":"#/components/schemas/DollarGreeks"}}},"legs":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"quantity":{"type":"number"},"underlying":{"type":"number"},"strike":{"type":"number"},"timeToExpiry":{"type":"number"},"optionType":{"$ref":"#/components/schemas/OptionType"},"volatility":{"type":"number"},"price":{"type":"number"},"contribution":{"type":"number"},"greeks":{"$ref":"#/components/schemas/Greeks"}}}},"positionCount":{"type":"integer"},"requestId":{"type":"string"},"computedAt":{"type":"string"}}},"ScenarioShock":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","maxLength":64},"spotShock":{"type":"number","default":0,"description":"Relative spot move; newS = S*(1+spotShock)"},"volShock":{"type":"number","default":0,"description":"Relative vol move; newσ = σ*(1+volShock)"},"timeDecayDays":{"type":"number","minimum":0,"default":0,"description":"Calendar days of time decay; T reduced by days/365"}}},"PortfolioScenarioRequest":{"type":"object","title":"PortfolioScenarioRequest","description":"Reprice a portfolio under relative spot/vol shocks and calendar time decay.","required":["rate","positions","scenarios"],"additionalProperties":false,"properties":{"rate":{"type":"number"},"dividendYield":{"type":"number","minimum":0,"default":0},"positions":{"type":"array","minItems":1,"maxItems":100,"items":{"$ref":"#/components/schemas/PortfolioPosition"}},"scenarios":{"type":"array","minItems":1,"maxItems":20,"items":{"$ref":"#/components/schemas/ScenarioShock"}}}},"PortfolioScenarioResponse":{"type":"object","title":"PortfolioScenarioResponse","required":["base","scenarios","positionCount","scenarioCount","requestId","computedAt"],"properties":{"base":{"type":"object","required":["mtm","greeks"],"properties":{"mtm":{"type":"number"},"greeks":{"$ref":"#/components/schemas/Greeks"}}},"scenarios":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"shocks":{"type":"object","properties":{"spotShock":{"type":"number"},"volShock":{"type":"number"},"timeDecayDays":{"type":"number"}}},"mtm":{"type":"number"},"mtmChange":{"type":"number","description":"scenario mtm − base mtm"},"greeks":{"$ref":"#/components/schemas/Greeks"}}}},"positionCount":{"type":"integer"},"scenarioCount":{"type":"integer"},"requestId":{"type":"string"},"computedAt":{"type":"string"}}},"SurfacePointK":{"type":"object","additionalProperties":false,"required":["k","timeToExpiry","iv"],"properties":{"k":{"type":"number","description":"Log-moneyness k = ln(K/F)"},"timeToExpiry":{"type":"number","minimum":0,"description":"Tenor T in years"},"iv":{"type":"number","exclusiveMinimum":0,"description":"Implied vol σ > 0"}}},"SurfacePointStrike":{"type":"object","additionalProperties":false,"required":["strike","underlying","timeToExpiry","iv"],"properties":{"strike":{"type":"number","exclusiveMinimum":0},"underlying":{"type":"number","exclusiveMinimum":0,"description":"Forward or spot-as-forward F for this point"},"timeToExpiry":{"type":"number","minimum":0},"iv":{"type":"number","exclusiveMinimum":0}}},"SurfacePricingPoint":{"oneOf":[{"$ref":"#/components/schemas/SurfacePointK"},{"$ref":"#/components/schemas/SurfacePointStrike"}],"description":"Surface node as (k,T,iv) or (strike,underlying,T,iv) converted server-side to k=ln(K/F)"},"SurfacePricingLeg":{"type":"object","additionalProperties":false,"required":["underlying","strike","timeToExpiry","optionType"],"properties":{"underlying":{"type":"number","exclusiveMinimum":0,"description":"Forward mark or spot used as F for moneyness and as BS spot"},"strike":{"type":"number","exclusiveMinimum":0},"timeToExpiry":{"type":"number","minimum":0},"optionType":{"$ref":"#/components/schemas/OptionType"},"quantity":{"type":"number","default":1},"id":{"type":"string","maxLength":64}}},"PriceFromSurfaceRequest":{"type":"object","title":"PriceFromSurfaceRequest","description":"Price European options on a submitted IV surface via total-variance bilinear interpolation in log-moneyness k=ln(K/F). Duplicate (k,T) rejected. Soft warnings for calendar/butterfly issues; grid is not repaired.","additionalProperties":false,"required":["surfaceConvention","rate","surface","options"],"properties":{"surfaceConvention":{"type":"string","const":"log_moneyness_forward","description":"Only log_moneyness_forward is supported in v1"},"interpolation":{"type":"string","const":"total_variance_bilinear","default":"total_variance_bilinear"},"wingRule":{"type":"string","const":"flat_vol","default":"flat_vol","description":"Clamp to nearest edge vol; no wing model invented"},"rate":{"type":"number"},"dividendYield":{"type":"number","minimum":0,"default":0},"surface":{"type":"array","minItems":1,"maxItems":200,"items":{"$ref":"#/components/schemas/SurfacePricingPoint"}},"options":{"type":"array","minItems":1,"maxItems":50,"items":{"$ref":"#/components/schemas/SurfacePricingLeg"}}}},"ScenarioShockSurface":{"type":"object","additionalProperties":false,"description":"All fields optional (default 0). underlyingRel XOR underlyingAbs — reject if both set. Vol order: interpolate → volAbs → volRel → smileTwist*k.","properties":{"underlyingRel":{"type":"number","description":"Relative F shock applied to every leg"},"underlyingAbs":{"type":"number","description":"Absolute F shock (alternative to underlyingRel)"},"rateBp":{"type":"number","default":0,"description":"Rate shock in basis points"},"timeDays":{"type":"number","minimum":0,"default":0,"description":"Roll each T by timeDays/365 (floor at small epsilon), then interpolate σ"},"volAbs":{"type":"number","default":0,"description":"Add to interpolated σ"},"volRel":{"type":"number","default":0,"description":"Multiply interpolated σ after volAbs: (σ+volAbs)*(1+volRel)"},"smileTwist":{"type":"number","default":0,"description":"Extra tilt vs k: σ_used += smileTwist * k (vol points per unit log-moneyness)"}}},"ScenarioFromSurfaceRequest":{"type":"object","title":"ScenarioFromSurfaceRequest","description":"Book reval on an IV surface under sticky moneyness/strike/fixed_vol with optional F, rate, time, and vol shocks.","additionalProperties":false,"required":["surfaceConvention","rate","surface","positions","scenario"],"properties":{"surfaceConvention":{"type":"string","const":"log_moneyness_forward"},"interpolation":{"type":"string","const":"total_variance_bilinear"},"wingRule":{"type":"string","const":"flat_vol"},"rate":{"type":"number"},"dividendYield":{"type":"number","minimum":0,"default":0},"sticky":{"type":"string","enum":["moneyness","strike","fixed_vol"],"default":"moneyness","description":"After F→F′: moneyness reads k′=ln(K/F′); strike reads old k=ln(K/F_base); fixed_vol keeps σ from base k (still applies volAbs/volRel/twist)"},"surface":{"type":"array","minItems":1,"maxItems":200,"items":{"$ref":"#/components/schemas/SurfacePricingPoint"}},"positions":{"type":"array","minItems":1,"maxItems":50,"items":{"$ref":"#/components/schemas/SurfacePricingLeg"}},"scenario":{"$ref":"#/components/schemas/ScenarioShockSurface"}}},"PriceFromSurfaceResponse":{"type":"object","required":["results","warnings","requestId","computedAt"],"properties":{"results":{"type":"array","description":"Per-option price, interpolated σ, k, F, Greeks"},"book":{"type":"object","description":"Aggregated MTM + Greeks"},"units":{"type":"object"},"surfaceMeta":{"type":"object"},"warnings":{"type":"array","items":{"type":"string"}},"model":{"type":"string"},"requestId":{"type":"string"},"computedAt":{"type":"string","format":"date-time"}}},"ScenarioFromSurfaceResponse":{"type":"object","required":["legs","book","warnings","requestId","computedAt"],"properties":{"sticky":{"type":"string"},"scenario":{"type":"object","description":"Echo of applied scenario shocks"},"legs":{"type":"array","description":"Per-leg base vs scenario value, σ, k/F, sticky-σ Greeks"},"book":{"type":"object","description":"valueBase, valueScenario, deltaValue, greeksBase/Scenario"},"surfaceMeta":{"type":"object"},"warnings":{"type":"array","items":{"type":"string"},"description":"wing clamp, tenor extrapolate, both-shocks-set, T clipped, etc."},"model":{"type":"string"},"requestId":{"type":"string"},"computedAt":{"type":"string","format":"date-time"}}}},"securitySchemes":{"x402":{"type":"http","scheme":"bearer","bearerFormat":"x402","description":"x402 micropayment (HTTP 402). Settle USDC exact on Solana and/or Base, then retry with payment proof. Free discovery operations set security: [] and must not expect 402."}}},"x-payment":{"protocol":"x402","asset":"USDC","scheme":"exact","facilitators":{"payai":"https://facilitator.payai.network","cdp":"https://api.cdp.coinbase.com/platform/v2/x402"},"networks":[{"caip2":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp","alias":"solana","name":"Solana mainnet"},{"caip2":"eip155:8453","alias":"base","name":"Base mainnet","usdc":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}],"note":"payTo is only in PAYMENT-REQUIRED, not on free OpenAPI/discovery documents."},"security":[{"x402":[]}]}