# Portfolio risk API 4 endpoints under `https://apexvol.com/api/mcp/data`. Every call needs `Authorization: Bearer avmcp_`; tokens are issued to paid and trial accounts under Account, then API Access. Web version: https://apexvol.com/developers/risk-api | Endpoint | Plan | What it answers | |---|---|---| | `POST /hedge-recommendations` | Pro | How many SPY puts or shares neutralise my delta? | | `POST /portfolio-greeks` | Pro | What is my net delta, theta and vega across these positions? | | `POST /scenario-analysis` | Pro | What happens to my book if SPY drops 5% and IV rises 20% over 5 days? | | `POST /stress-tests` | Pro | How does my book hold up in a crash, a vol spike and a melt-up? | ## POST /hedge-recommendations Computes net portfolio delta and returns a share hedge and an option alternative on the hedge ticker sized to reach the target delta, with cost estimates and projected Greeks after the hedge. - **Units:** Deltas in share-equivalents; est_cost in dollars. - **Basis:** Share-equivalent hedge, not beta-weighted. Option hedge uses the live chain on hedge_ticker. - **Markdown:** https://apexvol.com/developers/risk-api/hedge-recommendations.md | Name | In | Default | Range | Meaning | |---|---|---|---|---| | `positions` (required) | body | | as /portfolio-greeks | The book. | | `hedge_ticker` | body | SPY | symbol | What to hedge with. | | `target_delta` | body | 0 | share-equivalents | Where to land. | ```bash curl -X POST "https://apexvol.com/api/mcp/data/hedge-recommendations" \ -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}], "hedge_ticker": "SPY", "target_delta": 0}' ``` - `current_delta, delta_gap, target_delta`: The gap to close. - `hedges[].type, action, contracts, strike, expiration, est_cost, description`: Each hedge. - `projected_greeks`: Greeks after the hedge. ## POST /portfolio-greeks Sums delta, theta and vega across positions, returns exposure as a share of value, daily decay, a risk label and a per-ticker breakdown. - **Units:** total_delta in share-equivalents; total_theta in dollars per day; total_vega in dollars per vol point; percentages in percent. - **Basis:** Per-share Greeks come from the positions you pass (take them from /chain); stock positions count delta 1 per share. - **Markdown:** https://apexvol.com/developers/risk-api/portfolio-greeks.md | Name | In | Default | Range | Meaning | |---|---|---|---|---| | `positions` (required) | body | | array of {ticker, position_type STOCK|CALL|PUT, quantity, strike, expiration, entry_price, current_price, delta, gamma, theta, vega, iv} | The book. | ```bash curl -X POST "https://apexvol.com/api/mcp/data/portfolio-greeks" \ -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}]}' ``` - `portfolio_summary.total_delta, total_theta, total_vega`: The net Greeks. - `portfolio_summary.risk_level, delta_exposure_pct, daily_decay_pct`: The read. - `positions_by_ticker.`: Per-ticker delta, theta, vega and value. ## POST /scenario-analysis 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. - **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. - **Markdown:** https://apexvol.com/developers/risk-api/scenario-analysis.md | 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. | ```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}]}' ``` - `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. ## POST /stress-tests Runs the fixed set of scenarios (crash, correction, vol spike, rally and more) on your positions and returns the estimated P&L and contributions for each. - **Units:** As /scenario-analysis. - **Basis:** Same Greeks-based estimate as /scenario-analysis. - **Markdown:** https://apexvol.com/developers/risk-api/stress-tests.md | Name | In | Default | Range | Meaning | |---|---|---|---|---| | `positions` (required) | body | | as /portfolio-greeks | The book. | ```bash curl -X POST "https://apexvol.com/api/mcp/data/stress-tests" \ -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[].scenario_name, stock_move_pct, iv_change_pct, days_forward`: The scenario. - `scenarios[].estimated_pnl, estimated_pnl_pct`: The outcome. - `current_value`: Starting value. Conventions: https://apexvol.com/developers/conventions. Errors: https://apexvol.com/developers/errors. Whole API in one file: https://apexvol.com/docs/api/apexvol-api.md