American option model migration

Select a model

For American exercise, auto selects QdFp with an empty or omitted schedule and the cash model with a nonempty schedule. Explicit QdFp with cash events is refused. European Auto remains Black–Scholes–Merton. BS1993 also exposes its implemented Greeks and implied volatility.

bjerksund_stensland_2002 returns 422 invalid_field. It is never silently interpreted as a replacement. Change the selector and any model_version pin together, and revalidate prices and risk results: these are different numerical models.

Risk v0.43.5 numerical migration

The candidate uses the optimized QdFp production price solver with absolute error at most 1e-4 × max(spot, strike), including independent reference uncertainty. This intentionally changes prices from v0.42.x. Greeks retain the stronger scheme and quantity-specific acceptance criteria; the price cap is not a Greek or implied-volatility error guarantee. Step and iteration consistency checks are empirical indicators, not certified total-error bounds.

IV solves the served price and reports its repricing residual. The v0.43.0 migration study recorded ten previously solved quotes refused and five newly solved quotes. On a tiny-time-value quote, a common solved IV moved from about 0.005 to 0.00334 despite a tiny price residual. Handle unsupported_accuracy_contract explicitly and revalidate numerical assumptions. The selector and qd_fixed_point/1 identity are unchanged; exact engine version and revision in metadata identify this migration.

Requests

Load FERRO_API_KEY using the key setup instructions. The examples use synthetic contracts. Set API_BASE_URL to the test deployment where the new models are enabled.

curl --fail-with-body "$API_BASE_URL/v1/price" \
  --header "Authorization: Bearer $FERRO_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "exercise_style": "american",
  "pricing_model": "black_scholes_merton_qdfp",
  "model_version": "qd_fixed_point/1",
  "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
}'

curl --fail-with-body "$API_BASE_URL/v1/price" \
  --header "Authorization: Bearer $FERRO_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "exercise_style": "american",
  "pricing_model": "black_scholes_merton_fd",
  "model_version": "cash_dividend_american/1",
  "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
    },
    {
      "ex_time_years": 0.5,
      "cash_amount": 1.25
    }
  ]
}'

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

Prices and cash amounts use the same currency units as spot and strike. Rates, yield and volatility are decimals; expiry and ex-dividend times are year fractions from valuation on the same basis. No calendar conversion is performed. IV replaces volatility with market_price; it returns a decimal volatility and explicit solver diagnostics.

Capabilities and results

Live cash pricing is qualified for spot/strike from 0.8 to 1.2, expiry from 91/365 to 2 years, volatility from 0.15 to 0.5, rates from 0 to 0.05, and continuous yield from 0 to 0.02. It supports at most two live cash events totaling at most 12.5% of spot. The wire decoder's 16-event structural ceiling does not expand this numerical capability. IV must have an identifiable solution in the engine's supported region.

Price support does not imply derivative or inverse support. Payoff kinks, expiry Greeks, exercise plateaus and numerical conditioning can require refusal. QdFp can return delta, gamma, theta, vega, rho, vanna, volga, charm, veta and color, with individual refusal reasons when needed; time derivatives are annualized and volatility/rate sensitivities are per unit decimal change. The cash model also implements all ten quantities with independent value/refusal results. Its daily theta, charm, veta and color are converted to the API's annual basis exactly once. The API does not fill missing cash sensitivities with zeros.

Successful results report qd_fixed_point/1 or cash_dividend_american/1. Metadata separately identifies the exact engine build. JSON, raw Protobuf and unary gRPC share the same resolution and execution. Batch output preserves order; a resolution failure rejects the envelope before reservation, while an execution failure appears as a per-item error.

Errors and charges

HTTP 422 distinguishes invalid_field, model_domain, model_validity (including a nonunique inverse), unsupported_accuracy_contract, and derivative_not_resolved. Some numerical failures remain 500 pricing_failed. Protobuf HTTP errors use the same problem JSON; gRPC carries the same error details with the mapped status.

Internal units_charged are execution weights, not commercial CUs. They are zero on numerical refusal. Commercial fcu_charged follows the pinned policy: pre-execution rejection is free, while a request already committed at execution start can retain its quoted charge even if the engine refuses. Check both the policy metadata and error details.

The new QdFp schedule provisionally retains 20 CU for price, 250 CU for implied volatility, 450 CU for all-ten Greeks, and 700 CU for fused analytics, per contract. Single and batch requests use the same rates, with no request surcharge or minimum charge. These are commercial prices, not measured cost equivalence; calibration and workload-limit qualification are required before deployment. European prices and regime analysis at 100 CU per request remain unchanged. See the compute rates and usage calculator.