Pricing models and available Greeks

Public model discovery

Set API_BASE_URL to the API instance you are using. GET /v1/pricing/models returns the same catalog to every caller. It needs no credentials, request body or query parameters, performs no numerical work and consumes no Compute Units. The response is JSON; an incompatible Accept header receives 406.

curl --fail-with-body "$API_BASE_URL/v1/pricing/models"

The response contains a models array. Each entry includes id, name, version, model_version, aliases, underlying_model, method, exercise_styles, dividend_support, operations, greeks, guidance, constraints and notes. The HTTP x-request-id identifies the discovery request; the body has no numerical or billing receipt.

Use id as the JSON pricing_model selector and the exact model_version value if you want to pin its algorithm revision. Do not construct that pin by joining other fields: historical version identities remain stable through a selector rename.

auto is a selection rule, not another model: European requests select analytic BSM; American requests select QdFp, or finite difference when the cash-dividend schedule is nonempty. Retired BS2002 is excluded from the catalog and remains an explicit migration error.

QdFp numerical contract in Risk v0.43.5

QdFp pricing now uses the optimized fixed-work solver. Its absolute price-error cap is 1e-4 × max(spot, strike), including independent reference uncertainty. This replaces the earlier relative price cap. Greeks retain their stronger scheme and quantity-specific acceptance criteria; they are not derivatives of the solver's discrete scheme-selection jump. Step and iteration consistency checks are empirical indicators, not certified total-error bounds.

IV inverts the served price. A small reported price residual does not bound the error against exact-American implied volatility, especially for tiny time values. Some quotes accepted by v0.42.x now return unsupported_accuracy_contract, and some formerly refused quotes now solve. Pin the deployed engine build when numerical reproducibility matters: qd_fixed_point/1 and the request selector remain unchanged across this numerical migration.

Return the available sensitivities

POST /v1/greeks and POST /v1/analytics, including their ordered batch forms and gRPC equivalents, retain the price and each resolved Greek. They do not require all ten sensitivities to succeed. These computation requests still require the normal API key and usage accounting.

The example uses a synthetic American put and one cash dividend. Load FERRO_API_KEY using the key setup instructions.

curl --fail-with-body "$API_BASE_URL/v1/greeks" \
  --header "Authorization: Bearer $FERRO_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"exercise_style":"american","pricing_model":"black_scholes_merton_fd","option_type":"put","spot":100,"strike":105,"time_to_expiry_years":0.75,"risk_free_rate":0.04,"dividend_yield":0.01,"volatility":0.3,"dividend_schedule":[{"ex_time_years":0.25,"cash_amount":1}]}'

Every present Greek is a finite number; a resolved zero is 0.0. An unavailable Greek is omitted and has an entry under greeks.unavailable with a code and message. Never replace a missing value with zero. A partial result is HTTP 200; malformed inputs, a failed price or inverse, infrastructure failures and unexpected engine failures still use the normal error response.

• unsupported_quantity: this engine path does not implement the quantity.
• model_domain or model_validity: the requested derivative is outside the model or validity domain for these inputs.
• unsupported_accuracy_contract: the engine cannot offer its accuracy contract for this quantity at these inputs.
• derivative_not_resolved: numerical refinement or rounding checks did not resolve the derivative.

All four catalog models implement delta, gamma, theta, vega, rho, vanna, volga, charm, veta and color. The cash finite-difference report preserves each resolved quantity when another is refused. An implemented quantity can still be unavailable for a particular input; absence is never zero. Theta, charm, veta and color are annualized; volatility and rate sensitivities are per unit decimal change.

Time derivatives are per year; vega is per unit volatility and rho per unit rate. Fused analytics with a premium solves IV once and retains that result if individual derivatives are unavailable. Successful partial results follow the same execution-start charging rules as other computations.

Input limits and migration

The catalog describes implemented capabilities, not guaranteed convergence at every input. Structured constraints describe selected live-contract limits; notes explain exceptions. An empty constraint list does not mean unrestricted input. The numerical engine remains authoritative, including stricter per-Greek regions.

The cash-dividend solver admits live contracts with spot/strike from 0.8 to 1.2, expiry from 91/365 to 2 years, volatility from 0.15 to 0.5, rate from 0 to 0.05, yield from 0 to 0.02, and at most two dividends before expiry totaling at most 12.5% of spot. IV searches that volatility band. The wire limit remains 16 supplied events; events at or after expiry do not affect price.

This beta revision makes Greek values optional and reports individual refusals. The API contract remains 0.1.0; the schema digest identifies the exact revision. Regenerate Protobuf clients: existing numeric field numbers remain, but Greek fields now carry explicit presence and an unavailable-reason map. Older clients cannot distinguish an absent double from zero. Existing gRPC method names are retained.

qd_fixed_point and cash_dividend_american remain accepted JSON input aliases. Responses use the canonical IDs above. The compatible version pins remain qd_fixed_point/1 and cash_dividend_american/1; Protobuf enum numbers and names remain unchanged. See the American model migration guide for the separate BS2002 numerical migration.

The catalog lists compiled capabilities, independently of account entitlements. The queued policy enables QdFp alongside BSM and regime; cash-dividend and BS1993 models remain outside that commercial policy. Their protected computations return 403 not_entitled until separately enabled.

This contract is pending review and deployment. Local verification does not establish public availability.