stress_whatif
Simulate hypothetical options under market stress to compare your portfolio's worst-case P&L with and without the added legs, revealing how the trough moves.
Instructions
The same stress run, with hypothetical legs added — three curves and three troughs: the portfolio as it stands, the portfolio plus the legs, and the difference.
This is what replaces reading Risk Navigator's What-If by hand: "if I add N puts at strike K expiring E, where does the trough move to?"
Read all three troughs. The trough of the difference is not the difference of the troughs — adding protection moves where the worst point sits as well as how deep it is, and comparing only the depths hides the move. A structure that lifts the bottom by very little may still have pushed it from −8% out to −15%, which is the part that matters.
Hypothetical options are priced off IB's current model greeks for those
exact contracts, so both curves start from the same volatilities and the
difference is the structure alone. A leg that cannot be resolved or priced
is reported in legProblems and left out of the second curve; the
comparison then covers only the legs that did resolve, and says so.
With breakdown='expiry' all three curves are broken out by settlement
date, and the difference curve's pnl_by_expiry is where the structure
actually landed: the expiry you traded against moves and the ones you did
not read zero, which is how a hedge is told apart from a change of subject.
A short expiry whose row goes to roughly nothing in withLegs is one the
structure has closed out.
Nothing is sent to IB's order path here — this is pure local repricing. For what the structure costs in margin, use whatif_order.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| legs | Yes | Hypothetical legs to add. Each is either a conid, or symbol+secType+expiry+strike+right, with action BUY/SELL and a quantity. | |
| betas | No | ||
| scope | No | equity | |
| shocks | Yes | Underlying moves as fractions, as above. | |
| vol_bump | No | ||
| vol_mode | No | sticky_strike | |
| breakdown | No | Which per-point P&L breakdowns to return. 'symbol' — the default and what this server has always returned — groups by root, which on an options book collapses every ES expiry under one 'ES' key. 'expiry' groups by the option's SETTLEMENT date instead ('ES 2026-10-30'), which is the breakdown that answers 'which expiry is holding the trough down, and which short do I buy back'. 'both' returns the two of them and 'none' neither. Positions with no expiry get a key naming their class ('ES (future)', 'AAPL (equity)') so the breakdown still sums to the point's total and can be checked against it. Responses are large: a book on nine expiries pays for the second dictionary at every one of twenty-six shocks, so ask for 'both' only when you want both, and 'none' when you only want the curve. | symbol |
| fetch_skew | No | ||
| risk_groups | No | ||
| default_beta | No | ||
| vol_slope_up | No | ||
| valuation_date | No | Value the curve at this ISO date, e.g. '2026-09-30', instead of counting the days out by hand into date_offset_days. Mutually exclusive with it. No calendar magic: the date is the date, weekend or not, and time to expiry is ACT/365 throughout. The P&L is still measured FROM today at today's prices and volatilities, with the clock rolled forward — it is decay, not a forecast. | |
| vol_slope_down | No | ||
| date_offset_days | No | ||
| bond_rate_shift_bp | No | ||
| bond_duration_years | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||