Vol Carry Strategy API

Endpoint

GET /v1/strategies/vol-carry/{symbol}

Auth required (X-Api-Key) Rate Limited: Yes Alpha plan+

Parameters

Name	In	Required	Default	Description
`symbol`	path	yes	-	Underlying symbol
`expiry`	query	no	nearest upcoming expiry	`yyyy-MM-dd`. Target expiry for structure selection and context.
`minOpenInterest`	query	no	`250`	Minimum OI a leg must have to be selected.
`targetShortDelta`	query	no	`0.25`	Target delta for the short leg.
`maxWidth`	query	no	`10.0`	Maximum spread/wing width, in strike points.
`minCredit`	query	no	`0.10`	Minimum credit a candidate must collect.

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://lab.flashalpha.com/v1/strategies/vol-carry/SPY?targetShortDelta=0.20&maxWidth=10"

import requests

resp = requests.get(
    "https://lab.flashalpha.com/v1/strategies/vol-carry/SPY",
    params={"targetShortDelta": 0.20, "maxWidth": 10},
    headers={"X-Api-Key": "YOUR_API_KEY"}
)
data = resp.json()
print(f"{data['decision']} (score {data['score']}, regime {data['regime']})")

const resp = await fetch(
  "https://lab.flashalpha.com/v1/strategies/vol-carry/SPY?targetShortDelta=0.20&maxWidth=10",
  { headers: { "X-Api-Key": "YOUR_API_KEY" } }
);
const data = await resp.json();
console.log(`${data.decision} (score ${data.score}, regime ${data.regime})`);

API Key

Response

Returns the standard strategy decision envelope. The metrics and regime fields are specific to this strategy (see below). When the historical VRP path is unavailable for the symbol, the endpoint returns decision: insufficient_data with regime: vrp_unavailable.

{
  "strategy": "vol_carry",
  "symbol": "SPY",
  "timestamp": "2026-06-05T14:32:11Z",
  "decision": "candidate",
  "score": 72,
  "confidence": 0.83,
  "regime": "rich_iv_stable_realized_vol",
  "best_structures": [
    {
      "rank": 1,
      "structure": "short_put_spread",
      "expiry": "2026-06-19",
      "legs": [
        { "action": "sell", "type": "put", "strike": 588, "delta": -0.25, "premium": 1.42, "quantity": 1 },
        { "action": "buy",  "type": "put", "strike": 578, "delta": -0.12, "premium": 0.72, "quantity": 1 }
      ],
      "credit": 0.70,
      "debit": null,
      "max_profit": 0.70,
      "max_loss": 9.30,
      "breakevens": [587.30],
      "edge_score": 72,
      "liquidity_score": 0.88
    }
  ],
  "metrics": {
    "vrp": 0.041,
    "vrp_percentile": 0.82,
    "underlying_price": 589.12
  },
  "risk_flags": [],
  "why": ["Implied vol is rich versus realized and historical VRP sits in the top percentile."],
  "avoid_if": ["Realized vol trends higher or an earnings event lands before the target expiry."],
  "data_quality": { "score": 90, "warnings": [] }
}

Notable Metrics

Key
`atm_iv`
`realized_vol`
`vrp`
`vrp_z_score`
`vrp_percentile`
`used_real_metrics`
`skew_25d`
`risk_reversal_25d`
`term_slope`
`rv_change_5d`
`earnings_before_expiry`
`recommended_side`
`underlying_price`

Regime Values

rich_iv_stable_realized_vol
fair_iv_neutral_realized_vol
cheap_iv_or_unstable_realized_vol
vrp_unavailable (insufficient-data case)

Errors

Status	`error`	When
`400`	`invalid_expiry`	`expiry` is present but not `yyyy-MM-dd`.
`403`	`tier_restricted`	Caller is below the Alpha plan.
`404`	`symbol_not_found`	No market data for the symbol.

About

Vol carry measures the volatility risk premium: how rich implied vol is versus realized vol, ranked against the symbol's own history via VRP percentile and z-score. It folds in skew, the term slope, the 5-day realized-vol trend, and an earnings check to judge whether selling vol is favourable right now.

When carry is rich and realized vol is stable, the strategy proposes short put spreads or iron condors at the target short delta. It returns decision: insufficient_data (regime: vrp_unavailable) when the historical VRP path is missing for the symbol.

Common Use Cases

Rank the universe - sort by score to find the richest variance-risk premium to sell across a watchlist
Trade only clean signals - act when decision is candidate and skip no_setup reads where carry is thin
Drop in the proposed structure - pull best_structures[] for a short put-spread or iron-condor at a target short delta
Filter out blow-up risk - drop names where risk_flags[] flags rising realized vol or an earnings event inside the tenor
Size on conviction - scale premium sold by score and confidence rather than a fixed clip
Respect the guardrails - require a clean data_quality and read regime to confirm the carry environment before selling

Complementary endpoints

Strategy Signals overview - the shared decision envelope across every strategy
Yield Enhancement - turn the carry edge into a covered-call or cash-secured-put overlay
Term Structure - pick the tenor where the carry is richest