Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
description: 'Options-analytics API (token surface). Auth: `Authorization: Bearer avmcp_` on every request; tokens are issued to any paid or trial plan from Basic, and each endpoint follows the same tier as the web app. Rate limits: 60/min and 1,000/hr per token, plus a monthly allowance per account measured in upstream data requests, by plan. The remaining counts come back in the X-RateLimit-* and X-Monthly-Budget-Remaining headers on every response, and GET /api/mcp/data/me/usage returns the month''s meter with a per-endpoint breakdown. IV values are percentage points unless a payload says otherwise (`iv_units`). The same endpoints power the ApexVol MCP server for AI assistants: `pipx install apexvol-mcp` (PyPI), setup at https://apexvol.com/mcp. Docs: https://apexvol.com/docs/api.'
title: ApexVol Portfolio risk API
version: '1.30'
servers:
- url: https://apexvol.com
security:
- bearerAuth: []
tags:
- name: Portfolio risk
paths:
/api/mcp/data/hedge-recommendations:
post:
description: 'Delta-hedge recommendations. Computes net portfolio delta in shares of the hedge ticker (each name beta-weighted to it) and returns a stock hedge plus an option-based alternative on the hedge ticker to reach the target delta.
**Request body:** JSON body: positions (required, same schema as /portfolio-greeks), hedge_ticker (optional, default SPY), target_delta (optional, default 0)
**Response shape:**
```json
{
"success": true,
"data": {
"current_delta": 130.01,
"delta_gap": -130.01,
"delta_units": "SPY shares",
"hedge_ticker": "SPY",
"hedges": [
{
"action": "BUY",
"contracts": 3,
"delta_per_contract": -50.2,
"description": "BUY 3 SPY 2026-10-16 767 puts",
"details": "~-50 delta per contract at 9.66 mid (est. cost $2,897).",
"est_cost": 2897.28,
"expiration": "2026-10-16",
"option_type": "put",
"strike": 767.0,
"ticker": "SPY",
"type": "option"
}
],
"note": "Hedges close a -130 share delta gap in SPY, the same underlying as the book.",
"portfolio_greeks": {
"daily_decay_pct": 0.0307,
"delta_exposure_pct": 130.6481,
"risk_level": "LOW",
"total_cost_basis": 0,
"total_delta": 130.01,
"total_pnl": 75805.57,
"total_pnl_pct": 0,
"total_positions": 2,
"total_theta": 23.24,
"total_value": 75805.57,
"total_vega": -74.04,
"vega_risk_pct": 0.0977
},
"projected_greeks": {
"changes": {
"delta": {
"change": -130.0,
"change_pct": -99.9923,
"current": 130.01,
"projected": 0.01
},
"gamma": {
"change": 0.0,
"change_pct": 0.0,
"current": -1.3185,
"projected": -1.3185
},
"theta": {
"change": 0.0,
"change_pct": 0.0,
"current": 23.24,
"projected": 23.24
},
"vega": {
"change": 0.0,
"change_pct": 0.0,
"current": -74.04,
"projected": -74.04
}
},
"current_greeks": {
"charm": 30.337,
"delta": 130.01,
"gamma": -1.3185,
"rho": 27.849,
"theta": 23.24,
"vanna": 22.9064,
"vega": -74.04,
"vomma": -5.9186
},
"current_risk_level": "LOW",
"hedge_cost": 0,
"hedge_trades": [
{
"position_type": "STOCK",
"quantity": -130,
"ticker": "SPY"
}
],
"projected_greeks": {
"charm": 30.337,
"delta": 0.01,
"gamma": -1.3185,
"rho": 27.849,
"theta": 23.24,
"vanna": 22.9064,
"vega": -74.04,
"vomma": -5.9186
},
"projected_risk_level": "LOW",
"success": true,
"timestamp": "2026-09-24T14:43:10.209430"
},
"share_delta": 130.01,
"target_delta": 0.0,
"weighting": "same_underlying",
"weighting_basis": {}
}
}
```'
operationId: post_hedge_recommendations
requestBody:
content:
application/json:
schema:
properties:
hedge_ticker:
default: SPY
description: 'What to hedge with. Range: symbol.'
type: string
positions:
description: 'The book. Range: as /portfolio-greeks.'
type: string
target_delta:
default: 0
description: 'Where to land. Range: shares of hedge_ticker.'
type: integer
required:
- positions
type: object
required: true
responses:
'200':
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/PostHedgeRecommendationsResponse'
success:
type: boolean
type: object
description: 'Success: payload under `data` with `success: true`.'
'400':
description: A parameter is malformed; the error names it.
'401':
description: Missing, invalid, expired or revoked token.
'403':
description: The endpoint needs a higher plan than the token's owner has (required_tier in the body).
'404':
description: Unknown path (did_you_mean in the body) or a symbol with no listed options.
'424':
description: The data feed did not answer for this symbol; retry.
'429':
description: Per-token rate limit or the monthly allowance (budget_exceeded). Retry-After says how long, in seconds.
summary: Delta-hedge recommendations
tags:
- Portfolio risk
/api/mcp/data/portfolio-greeks:
post:
description: 'Aggregate portfolio Greeks with summary risk level and per-ticker breakdown.
**Request body:** JSON: positions [{ticker, position_type STOCK|CALL|PUT, quantity, strike?, expiration?, entry_price?, current_price?, delta?…}] — required
**Response shape:**
```json
{
"success": true,
"data": {
"portfolio_summary": {
"daily_decay_pct": 0.0234,
"delta_exposure_pct": 130.6218,
"risk_level": "LOW",
"total_cost_basis": 0,
"total_delta": 130.14,
"total_pnl": 76389.0,
"total_pnl_pct": 0,
"total_positions": 2,
"total_theta": 17.85,
"total_value": 76389.0,
"total_vega": -83.79,
"vega_risk_pct": 0.1097
},
"positions_by_ticker": {
"SPY": {
"delta": 130.14,
"positions": [
{
"charm": 0,
"current_price": 6.36,
"delta": -0.3014,
"entry_price": 0,
"expiration": "2026-10-09",
"gamma": 0,
"iv": 0.1365,
"position_type": "PUT",
"quantity": -1,
"rho": 0,
"stock_price": 0,
"strike": 755.0,
"theta": -0.1785,
"ticker": "SPY",
"vanna": 0,
"vega": 0.8379,
"vomma": 0
}
],
"theta": 17.85,
"value": 76389.0,
"vega": -83.79
}
},
"success": true,
"timestamp": "2026-09-08T08:07:44.450169"
}
}
```'
operationId: post_portfolio_greeks
requestBody:
content:
application/json:
schema:
properties:
positions:
description: 'The book. Range: array of {ticker, position_type STOCK|CALL|PUT, quantity, strike, expiration, entry_price, current_price, delta, gamma, theta, vega, iv}.'
items:
type: object
type: array
required:
- positions
type: object
required: true
responses:
'200':
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/PostPortfolioGreeksResponse'
success:
type: boolean
type: object
description: 'Success: payload under `data` with `success: true`.'
'400':
description: A parameter is malformed; the error names it.
'401':
description: Missing, invalid, expired or revoked token.
'403':
description: The endpoint needs a higher plan than the token's owner has (required_tier in the body).
'404':
description: Unknown path (did_you_mean in the body) or a symbol with no listed options.
'424':
description: The data feed did not answer for this symbol; retry.
'429':
description: Per-token rate limit or the monthly allowance (budget_exceeded). Retry-After says how long, in seconds.
summary: Aggregate portfolio Greeks with summary risk level and per-ticker breakdown
tags:
- Portfolio risk
/api/mcp/data/scenario-analysis:
post:
description: 'What-if scenario analysis across supplied price/vol scenarios.
**Request body:** JSON: positions (required), scenarios []
**Response shape:**
```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"
}
}
```'
operationId: post_scenario_analysis
requestBody:
content:
application/json:
schema:
properties:
positions:
description: 'The book. Range: as /portfolio-greeks.'
type: string
scenarios:
default: '[]'
description: 'What to test. Range: array of {stock_move_pct, iv_change_pct, days_forward}.'
items:
type: object
type: array
required:
- positions
type: object
required: true
responses:
'200':
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/PostScenarioAnalysisResponse'
success:
type: boolean
type: object
description: 'Success: payload under `data` with `success: true`.'
'400':
description: A parameter is malformed; the error names it.
'401':
description: Missing, invalid, expired or revoked token.
'403':
description: The endpoint needs a higher plan than the token's owner has (required_tier in the body).
'404':
description: Unknown path (did_you_mean in the body) or a symbol with no listed options.
'424':
description: The data feed did not answer for this symbol; retry.
'429':
description: Per-token rate limit or the monthly allowance (budget_exceeded). Retry-After says how long, in seconds.
summary: What-if scenario analysis across supplied price/vol scenarios
tags:
- Portfolio risk
/api/mcp/data/stress-tests:
post:
description: 'Standardized stress-test battery (crash, vol spike, …) with estimated P&L per scenario.
**Request body:** JSON: positions (required)
**Response shape:**
```json
{
"success": true,
"data": {
"current_value": 76389.0,
"scenarios": [
{
"days_forward": 1,
"delta_contribution": -28472.4537,
"estimated_pnl": -28491.5651,
"estimated_pnl_pct": -37.298,
"iv_change_pct": 100,
"new_portfolio_value": 47897.4349,
"scenario_name": "Market Crash (-20%)",
"stock_move_pct": -20,
"theta_contribution": 13.583,
"vega_contribution": -1102.4875
},
{
"days_forward": 1,
"delta_contribution": -13089.1178,
"estimated_pnl": -13237.0642,
"estimated_pnl_pct": -17.3285,
"iv_change_pct": 50,
"new_portfolio_value": 63151.9358,
"scenario_name": "Sharp Decline (-10%)",
"stock_move_pct": -10,
"theta_contribution": 13.583,
"vega_contribution": -534.6292
},
{
"days_forward": 1,
"delta_contribution": -5797.5674,
"estimated_pnl": -6028.1085,
"estimated_pnl_pct": -7.8913,
"iv_change_pct": 25,
"new_portfolio_value": 70360.8915,
"scenario_name": "Moderate Decline (-5%)",
"stock_move_pct": -5,
"theta_contribution": 13.583,
"vega_contribution": -260.8316
}
],
"success": true,
"timestamp": "2026-09-08T08:07:46.937252"
}
}
```'
operationId: post_stress_tests
requestBody:
content:
application/json:
schema:
properties:
positions:
description: 'The book. Range: as /portfolio-greeks.'
type: string
required:
- positions
type: object
required: true
responses:
'200':
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/PostStressTestsResponse'
success:
type: boolean
type: object
description: 'Success: payload under `data` with `success: true`.'
'400':
description: A parameter is malformed; the error names it.
'401':
description: Missing, invalid, expired or revoked token.
'403':
description: The endpoint needs a higher plan than the token's owner has (required_tier in the body).
'404':
description: Unknown path (did_you_mean in the body) or a symbol with no listed options.
'424':
description: The data feed did not answer for this symbol; retry.
'429':
description: Per-token rate limit or the monthly allowance (budget_exceeded). Retry-After says how long, in seconds.
summary: Standardized stress-test battery (crash, vol spike, …) with estimated P&L per…
tags:
- Portfolio risk
components:
schemas:
PostStressTestsResponse:
properties:
current_value:
type: number
scenarios:
items:
properties:
days_forward:
type: integer
delta_contribution:
type: number
estimated_pnl:
type: number
estimated_pnl_pct:
type: number
iv_change_pct:
type: integer
new_portfolio_value:
type: number
scenario_name:
type: string
stock_move_pct:
type: integer
theta_contribution:
type: number
vega_contribution:
type: number
type: object
type: array
success:
type: boolean
timestamp:
type: string
type: object
PostScenarioAnalysisResponse:
properties:
current_value:
type: number
scenarios:
items:
properties:
days_forward:
type: integer
delta_contribution:
type: number
estimated_pnl:
type: number
estimated_pnl_pct:
type: number
iv_change_pct:
type: integer
new_portfolio_value:
type: number
scenario_name:
type: string
stock_move_pct:
type: integer
theta_contribution:
type: number
vega_contribution:
type: number
type: object
type: array
success:
type: boolean
timestamp:
type: string
type: object
PostHedgeRecommendationsResponse:
properties:
current_delta:
type: number
delta_gap:
type: number
delta_units:
type: string
hedge_ticker:
type: string
hedges:
items:
properties:
action:
type: string
contracts:
type: integer
delta_per_contract:
type: number
description:
type: string
details:
type: string
est_cost:
type: number
expiration:
type: string
option_type:
type: string
strike:
type: number
ticker:
type: string
type:
type: string
type: object
type: array
note:
type: string
portfolio_greeks:
properties:
daily_decay_pct:
type: number
delta_exposure_pct:
type: number
risk_level:
type: string
total_cost_basis:
type: integer
total_delta:
type: number
total_pnl:
type: number
total_pnl_pct:
type: integer
total_positions:
type: integer
total_theta:
type: number
total_value:
type: number
total_vega:
type: number
vega_risk_pct:
type: number
type: object
projected_greeks:
properties:
changes:
properties:
delta:
properties:
change:
type: number
change_pct:
type: number
current:
type: number
projected:
type: number
type: object
gamma:
properties:
change:
type: number
change_pct:
type: number
current:
type: number
projected:
type: number
type: object
theta:
properties:
change:
type: number
change_pct:
type: number
current:
type: number
projected:
type: number
type: object
vega:
properties:
change:
type: number
change_pct:
type: number
current:
type: number
projected:
type: number
type: object
type: object
current_greeks:
properties:
charm:
type: number
delta:
type: number
gamma:
type: number
rho:
type: number
theta:
type: number
vanna:
type: number
vega:
type: number
vomma:
type: number
type: object
current_risk_level:
type: string
hedge_cost:
type: integer
hedge_trades:
items:
properties:
position_type:
type: string
quantity:
type: integer
ticker:
type: string
type: object
type: array
projected_greeks:
properties:
charm:
type: number
delta:
type: number
gamma:
type: number
rho:
type: number
theta:
type: number
vanna:
type: number
vega:
type: number
vomma:
type: number
type: object
projected_risk_level:
type: string
success:
type: boolean
timestamp:
type: string
type: object
share_delta:
type: number
target_delta:
type: number
weighting:
type: string
weighting_basis:
properties: {}
type: object
type: object
PostPortfolioGreeksResponse:
properties:
portfolio_summary:
properties:
daily_decay_pct:
type: number
delta_exposure_pct:
type: number
risk_level:
type: string
total_cost_basis:
type: integer
total_delta:
type: number
total_pnl:
type: number
total_pnl_pct:
type: integer
total_positions:
type: integer
total_theta:
type: number
total_value:
type: number
total_vega:
type: number
vega_risk_pct:
type: number
type: object
positions_by_ticker:
properties:
SPY:
properties:
delta:
type: number
positions:
items:
properties:
charm:
type: integer
current_price:
type: number
delta:
type: number
entry_price:
type: integer
expiration:
type: string
gamma:
type: integer
iv:
type: number
position_type:
type: string
quantity:
type: integer
rho:
type: integer
stock_price:
type: integer
strike:
type: number
theta:
type: number
ticker:
type: string
vanna:
type: integer
vega:
type: number
vomma:
type: integer
type: object
type: array
theta:
type: number
value:
type: number
vega:
type: number
type: object
type: object
success:
type: boolean
timestamp:
type: string
type: object
securitySchemes:
bearerAuth:
description: ApexVol API token (avmcp_...) from apexvol.com/account, API Access.
scheme: bearer
type: http