Risk Engine API: Position Risk Flags, Hedges & VaR OPEN BETA

Endpoint

POST https://lab.flashalpha.com/v1/risk/analyze

Authenticate with your API key in the X-Api-Key header (find it on your profile page). The call is stateless: nothing about your positions is stored between calls apart from the beta telemetry noted above. Body limit 256 KB; up to 25 positions, 50 legs per position, 200 legs total, 20 distinct symbols per request.

Quick Start

Analyze a 10-lot short put. Note what is not in this request: no spot, no impliedVol. The engine resolves both from live data, nets your legs, computes dollar greeks and raises flags:

curl -X POST "https://lab.flashalpha.com/v1/risk/analyze" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "positions": [{
      "symbol": "SPY",
      "legs": [{
        "action": "sell", "type": "put", "strike": 440,
        "expiry": "2026-09-18", "quantity": 10
      }]
    }]
  }'

The response carries flags (stable codes, never prose to parse), hedges, and a portfolio rollup:

{
  "status": "OK",
  "flag_schema": "risk.flags.v1",
  "flags": [
    { "code": "uncovered_short_put", "category": "coverage", "severity": "high",
      "symbol": "SPY", "data": { "uncovered_contracts": 10 } },
    { "code": "undefined_risk_position", "category": "structure", "severity": "high" },
    { "code": "net_short_gamma", "category": "greeks", "severity": "high" }
  ],
  "hedges": [],
  "portfolio": { "dollar_delta": 154820, "dollar_gamma": -9120 }
}

You Only Supply Positions

spot and per-leg impliedVol are optional. Omit them and the engine resolves the live spot for each symbol and the live implied vol for each strike from FlashAlpha's own market data, using your API key so your plan's data entitlements apply. That is the whole point: you describe what you hold, the engine sources everything else.

Supply them explicitly whenever you want to pin a scenario - a what-if, a back-test, a stress at a level that is not the current market - and the engine uses your values untouched. If a value is omitted and cannot be resolved you get a 400 naming exactly which input to provide: spot_unavailable or iv_unavailable.

Prefer clicking to typing? The interactive playground builds a book from live option-chain dropdowns, runs it through the engine, and shows you the exact JSON it sent.

Request Shape

Each position carries a symbol and either option legs or a delta-1 exposure (shares/CFD). Everything else is optional: spot and per-leg impliedVol (resolved live when omitted), today (valuation date, defaults to the current US-Eastern trading date), rate, dividendYield, multiplier (default 100), beta. Optional per request:

• thresholds - absolute dollar-greek limits; breaches come back as delta_breach / gamma_breach / vega_breach / theta_breach flags.
• mandate.deltaTarget - a book-level target (even 0). Every position's dollar delta is netted and compared once, so one deviation flag is raised for the whole book, not one per position.
• include - any of risks, hedges, portfolio (defaults on) and metrics (opt-in: VaR, Monte Carlo, stress grid, breakevens, assignment probabilities).

The full field-by-field schema with every validation rule is in the canonical reference, /docs/risk-engine.md.

Risk Flags

Flags are stable enum codes under the risk.flags.v1 contract - codes are added over time, never renamed. Severities: info, warn, high, critical. Currently emitted families:

• Coverage - uncovered_short_call, uncovered_short_put, covered_call, naked_short_underlying, non_coterminal_coverage (a protective long that expires before the short it covers).
• Structure - unbounded_loss, undefined_risk_position, defined_risk_position.
• Expiry - expired_leg_present, expiring_today_position, short_leg_expiring_today, near_expiry_position, multi_expiry_position.
• Assignment & pin - short_strike_through_spot, itm_short_near_expiry, atm_short_near_expiry_pin, pin_risk_short_strike.
• Greek posture - net_short_gamma, net_long_gamma, net_short_vega, net_long_vega, negative_theta, positive_theta, short_gamma_short_vega.
• Thresholds & mandate - delta_breach, gamma_breach, vega_breach, theta_breach, delta_target_deviation.

Hedge Suggestions

A delta-1 underlying hedge is proposed only for delta problems: a posted mandate, or a delta threshold breach (hedged toward flat).

Mandate hedges are book-level. If the whole book is one symbol, you get one concrete trade sized to move the book to the target. If it spans several symbols there is no single delta-1 instrument that closes the gap, so the engine returns an explicit feasible: false entry naming the shortfall rather than a set of per-position trades that would each overshoot the target. Threshold breaches stay per position, because a breach belongs to the position that breached it.

Gamma/vega/theta-only breaches return an explicit feasible: false entry instead of a wrong trade. Expiry-day (0DTE) legs stay live in the greeks rather than dropping to zero.

Metrics (opt-in)

Include "metrics" to get, per position: max loss / max profit (null = unbounded), breakevens, risk-neutral assignment probabilities per net-short strike, quantile VaR (full revaluation across the confidence band, so long-straddle-style interior losses are measured correctly), seeded Monte Carlo VaR/CVaR (deterministic per seed), and a 7×3 spot × IV stress grid. Model: Black-Scholes on your supplied IVs, GBM paths.

Errors

Engine errors use { "status": "ERROR", "error": "<code>", "message": "..." }. The ones you will meet first:

• 401 missing_api_key / invalid_api_key - header absent, or the key was explicitly rejected.
• 429 rate_limited - over 60 requests this minute for your key; honor Retry-After.
• 503 auth_unavailable - account verification is degraded. Your key was NOT rejected - retry, do not rotate keys.
• 400 spot_unavailable / iv_unavailable - you omitted a value and the engine could not resolve it live. The message names the symbol (and expiry/strike) so you know exactly what to supply.
• 400 validation codes - e.g. invalid_iv, expiry_in_past, invalid_today, duplicate_position_id, too_many_legs. The message names the exact position and leg.

All 24 validation codes with their exact conditions are tabulated in the canonical reference, /docs/risk-engine.md.

Common Use Cases

• Pre-trade checks: catch naked tails, undefined risk, and non-coterminal "protection" before an order goes out
• End-of-day book scan: pin risk and assignment exposure on everything expiring this week
• Delta-mandate monitoring: post a target once, alert on delta_target_deviation
• CFD / delta-1 books: dollar-delta rollups, beta-weighted exposure, stress grids - no option legs required