# POST /api/mcp/data/scenario-analysis

> What happens to my book if SPY drops 5% and IV rises 20% over 5 days?

For each scenario (stock move, IV change, days forward) returns the estimated P&L in dollars and percent, split into delta, vega and theta contributions, and the new portfolio value.

- **Family:** Portfolio risk (https://apexvol.com/developers/risk-api)
- **Plan:** Pro and above. Every call needs `Authorization: Bearer avmcp_<token>`; tokens are issued to paid and trial accounts under Account, then API Access.
- **Units:** stock_move_pct and iv_change_pct in percent; P&L in dollars.
- **Basis:** First-order Greeks-based estimate from the Greeks you pass; not a full re-pricing.
- **MCP tools:** `run_scenario_analysis`
- **Background:** https://apexvol.com/learn/options-risk-management

## Parameters

| Name | In | Default | Range | Meaning |
|---|---|---|---|---|
| `positions` (required) | body |  | as /portfolio-greeks | The book. |
| `scenarios` | body | [] | array of {stock_move_pct, iv_change_pct, days_forward} | What to test. |

## Request

```bash
curl -X POST "https://apexvol.com/api/mcp/data/scenario-analysis" \
     -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"positions": [{"ticker": "SPY", "position_type": "STOCK", "quantity": 100, "current_price": 770.25}, {"ticker": "SPY", "position_type": "PUT", "quantity": -1, "strike": 755.0, "expiration": "2026-10-09", "current_price": 6.359999999999999, "delta": -0.3014, "theta": -0.1785, "vega": 0.8379, "iv": 0.1365}], "scenarios": [{"stock_move_pct": -5, "iv_change_pct": 20, "days_forward": 5}]}'
```

## Response (captured 2026-09-08)

Real response, lists cut to the rows nearest the money. The envelope is `{"success": true, "data": ...}`.

```json
{
  "success": true,
  "data": {
    "current_value": 76389.0,
    "scenarios": [
      {
        "days_forward": 5,
        "delta_contribution": -5797.5674,
        "estimated_pnl": -5928.2762,
        "estimated_pnl_pct": -7.7606,
        "iv_change_pct": 20,
        "new_portfolio_value": 70460.7238,
        "scenario_name": "+-5% stock, 20% IV",
        "stock_move_pct": -5,
        "theta_contribution": 70.2965,
        "vega_contribution": -207.3894
      }
    ],
    "success": true,
    "timestamp": "2026-09-08T08:07:45.686052"
  }
}
```

## Fields

- `scenarios[].estimated_pnl, estimated_pnl_pct`: The outcome.
- `scenarios[].delta_contribution, vega_contribution, theta_contribution`: What drove it.
- `current_value, scenarios[].new_portfolio_value`: Before and after.

## Errors

- `401`: no or revoked token
- `429`: Retry-After seconds
- `403`: Pro plan required
- `400`: missing or malformed body
- Full list: https://apexvol.com/developers/errors

## Ask it in an MCP client

- What happens to my positions if SPY falls 5% and IV jumps 20% in 5 days?
- Run a +3% / -10 vol scenario on my NVDA book.
- Show P&L for three scenarios on these positions.

Conventions for units, bases and timestamps: https://apexvol.com/developers/conventions