A Position Risk API That Sources Its Own Market Data - Flags, Hedges and VaR From Positions Alone

Every options risk tool asks you the same three questions before it will say anything useful: what is the underlying trading at, what is the implied vol of each leg, and what is your valuation date. Answer them wrong and every number that follows is wrong too.

That is a strange thing to demand from a customer whose data vendor already knows all three. The FlashAlpha Risk Engine takes the other approach: you say what you hold, and the engine sources the rest.

The smallest useful request

This is a complete, valid request. There is no spot price in it and no implied vol:

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

The engine resolves the live spot for SPY and the live implied vol for each of those two strikes, then values the structure. What comes back is a put credit spread correctly identified as defined risk, with net short gamma, net short vega, a breakeven, a max loss bounded by the width less the credit, and a one-day VaR.

If you would rather pin the scenario - a what-if at a level the market is not at, a back-test against a historical mark, a stress with vol you choose - supply spot and impliedVol explicitly and the engine uses your values untouched. Sourcing the data is a default, not a policy.

Flags are codes, not prose

Risk output that reads well to a human is useless to a program. Every finding the engine returns is a stable enum code under the risk.flags.v1 contract, with a severity you can switch on:

{ "code": "uncovered_short_put", "category": "coverage", "severity": "high",
  "symbol": "SPY", "data": { "uncovered_contracts": 10 } }

Codes are added over time and never renamed, so a consumer written today keeps working. The families that matter most in practice:

• Coverage - uncovered_short_call, uncovered_short_put, naked_short_underlying, and the one that catches people out, non_coterminal_coverage: a protective long that expires before the short it is supposed to cover. Coverage is evaluated coterminally, so a reverse calendar is correctly reported as uncovered rather than hedged.
• Structure - unbounded_loss is upside-only by definition. A naked short put is large-but-floored, so it raises uncovered_short_put and undefined_risk_position but not unbounded_loss. Tools that conflate the two cry wolf on every put seller.
• Assignment and pin - short_strike_through_spot, itm_short_near_expiry (critical inside one day), pin_risk_short_strike when spot is sitting on a short strike into expiry.
• Greek posture - always on, no thresholds required. short_gamma_short_vega is the classic vol-spike blow-up shape: losses compound as spot moves and vol rises together.

Hedges you can actually execute, or an honest refusal

Post a mandate with a delta target and the engine sizes the trade that gets you there. The mandate is a book-level contract: every position's dollar delta is netted and compared to the target once. That distinction matters more than it sounds. A per-position interpretation of a single book target would tell a four-position trader to hedge each position to the target, quietly walking the book to four times it.

When the book is one symbol, the gap is closable and you get a concrete trade. When it spans several symbols there is no single delta-1 instrument that closes it, so the engine returns an explicit feasible: false naming the shortfall instead of a set of trades that would each overshoot. The same rule applies to gamma, vega and theta breaches: they cannot be neutralised with an underlying hedge, so the engine says so rather than proposing a delta trade that does not address the problem.

Refusing to answer is a feature. A risk tool that always emits a trade is a risk tool you cannot trust when the trade is wrong.

Metrics when you ask for them

Add "metrics" to include and each position also returns max loss and max profit (null where genuinely unbounded), breakevens, risk-neutral assignment probability per short strike, a quantile VaR, a seeded Monte Carlo VaR and CVaR, and a spot-by-IV stress grid. The VaR revalues across the whole confidence band rather than only at its edges, which matters for non-monotone payoffs: a long straddle's worst case sits at unchanged spot, and an edge-only method reports approximately zero risk for it.

Try it without writing JSON

The playground builds a book from live option-chain dropdowns - pick a symbol, an expiry, a strike, a side - runs it through the engine and shows the portfolio greeks, the flags sorted by severity, the hedges and the metrics. It also shows the exact JSON it sent, so you can copy it straight into your own client.

The Risk Engine is in open beta and works with any FlashAlpha API key, every plan included. The full contract, every flag code and every error code, is in the reference.