Yield Enhancement Strategy API

Historical trader-context additions: see expiry impact, strike dependency and income replay, plus versioned research packs. The new routes require the corresponding Historical service release. Income diagnostics distinguish quoted cash arithmetic from legacy mid-based rankings and absolute-delta assignment proxies; historical earnings calendars remain unverified.

Endpoint

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://lab.flashalpha.com/v1/strategies/yield-enhancement/SPY?structure=cash_secured_put&targetDelta=0.20"

import requests

resp = requests.get(
    "https://lab.flashalpha.com/v1/strategies/yield-enhancement/SPY",
    params={"structure": "cash_secured_put", "targetDelta": 0.20},
    headers={"X-Api-Key": "YOUR_API_KEY"}
)
data = resp.json()
print(f"{data['decision']} ({data['regime']}) score={data['score']}")

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

Response

Returns the standard strategy decision envelope. Every Strategy Signals endpoint returns this same shape; only metrics and regime change per strategy.

{
  "strategy": "yield_enhancement",
  "symbol": "SPY",
  "timestamp": "2026-10-20T15:01:44.2093386Z",
  "decision": "avoid",
  "score": 29,
  "confidence": 0.7,
  "regime": "covered_call_income",
  "best_structures": [
    {
      "rank": 1,
      "structure": "covered_call",
      "expiry": "2026-12-18",
      "legs": [
        {
          "action": "sell",
          "type": "call",
          "strike": 803,
          "delta": 0.25021779246090475,
          "premium": 5.44,
          "quantity": 1
        }
      ],
      "credit": 5.44,
      "debit": null,
      "max_profit": 5.44,
      "max_loss": null,
      "breakevens": [],
      "edge_score": 29,
      "liquidity_score": 78.11
    }
  ],
  "metrics": {
    "structure": "covered_call",
    "strike": 803,
    "delta": 0.25021779246090475,
    "premium": 5.44,
    "annualized_yield_pct": 0.0419,
    "assignment_probability": 0.2502,
    "upside_surrender_pct": 0.0407,
    "dte": 59,
    "earnings_before_expiry": false,
    "ex_dividend_risk": "not_modeled",
    "underlying_price": 771.5699999999999,
    "breakeven_price": null,
    "iv_rank_30d": null,
    "roll_candidate": {
      "expiry": "2026-12-31",
      "strike": 806,
      "delta": 0.25164451445527125,
      "premium": 5.880000000000001
    },
    "next_earnings_date": null,
    "days_to_next_earnings": null,
    "income_diagnostics": {
      "calculation_version": "income_diagnostics_v1",
      "position_basis": "one_standard_equity_option_contract",
      "deliverable_status": "standard_100_share_assumption_not_verified",
      "contract_multiplier": 100,
      "shares_required": 100,
      "bid_per_share": 5.42,
      "ask_per_share": 5.46,
      "mid_per_share": 5.4399999999999995,
      "credit_basis": "displayed_bid_not_guaranteed_fill",
      "quote_at": "2026-10-20T15:01:41Z",
      "quote_timestamp_status": "upstream",
      "gross_credit_usd": 542,
      "fees_per_contract_usd": null,
      "net_credit_usd": null,
      "stock_cost_basis_per_share": null,
      "collateral_usd": null,
      "collateral_basis": "stock_cost_basis_unavailable",
      "gross_income_period_return_pct": null,
      "net_income_period_return_pct": null,
      "period_days": 59,
      "gross_breakeven_price": null,
      "net_breakeven_price": null,
      "gross_max_profit_usd": null,
      "gross_max_loss_usd": null,
      "gross_capped_total_return_pct": null,
      "absolute_delta_proxy": 0.25021779246090475,
      "earnings_risk_status": "none_on_loaded_calendar",
      "ex_dividend_risk_status": "unknown",
      "methodology_url": "https://lab.flashalpha.com/llms/trader-context.md#earnings-and-income-additions"
    },
    "income_diagnostics_status": "available_standard_contract_assumption",
    "absolute_delta_proxy": 0.25021779246090475,
    "assignment_probability_method": "legacy_absolute_delta_proxy_not_calibrated_assignment_probability",
    "earnings_risk_status": "none_on_loaded_calendar",
    "legacy_quote_basis": "mid_not_guaranteed_fill",
    "legacy_annualized_yield_interpretation": "Arithmetic extrapolation using max(1,DTE); not a sustainable return forecast."
  },
  "risk_flags": [
    {
      "severity": "low",
      "code": "EX_DIVIDEND_RISK_NOT_MODELED",
      "message": "Ex-dividend assignment risk is not modeled — confirm independently before deploying."
    }
  ],
  "why": [
    "Short 803 call at 0.25Δ yields 4.2 % annualised, surrendering 4.1 % upside."
  ],
  "avoid_if": [],
  "data_quality": {
    "score": 90,
    "warnings": []
  },
  "endpoint_version": "2026.09.30",
  "data_as_of": {
    "node": "fa5",
    "equity_feed": "2026-10-20T15:01:43.727Z",
    "equity_options_feed": "2026-10-20T15:01:43Z",
    "index_feed": "2026-10-20T15:01:43.113Z",
    "index_options_feed": "2026-10-20T15:01:43Z",
    "futures_feed": "2026-10-20T15:01:42.41Z",
    "futures_options_feed": "2026-10-20T15:01:36.055Z",
    "flow_feed": "2026-10-20T15:01:00Z",
    "oi_feed": "2026-10-19T20:00:00Z",
    "macro_feed": "2026-10-19T21:00:20Z"
  }
}

Real response from the live API (2026-10-20 15:01 UTC), with lists shortened to three items. Download the full response (JSON).

Strategy-specific fields

Notable metrics keys (in addition to the always-present underlying_price):

regime values: covered_call_income, cash_secured_put_income, no_yield_candidate.

Income diagnostics

metrics.income_diagnostics shows the cash arithmetic for one assumed standard 100-share equity contract at the quoted bid. It is null for index and futures underlyings.

• Credit - gross_credit_usd = bid × 100; net_credit_usd subtracts feesPerContract (null when fees are not supplied).
• Collateral - collateral_usd is strike × 100 before credit for a cash-secured put, and stockCostBasis × 100 for a covered call.
• Period return - gross_income_period_return_pct = 100 × credit / collateral for this one period; covered calls add gross_capped_total_return_pct including the move to the strike.
• Breakeven and limits - gross_breakeven_price, net_breakeven_price, gross_max_profit_usd, gross_max_loss_usd, period_days.
• Quality - quote_at, quote_timestamp_status, earnings_risk_status (event_before_expiry, none_on_loaded_calendar or unknown), ex_dividend_risk_status (unknown) and methodology_url.

The legacy premium and ranking still use mid. assignment_probability is the absolute delta, a sensitivity proxy rather than a calibrated probability, and annualized_yield_pct is an arithmetic extrapolation of one period, not a sustainable return. Candidate selection is unchanged: every listed contract for the symbol is eligible (for SPX this includes SPXW weeklies). earnings_risk_status and income_diagnostics describe the selected contract; diagnostics are produced only for a standard-root equity contract.

Errors

About

This strategy scores income overlays on the chain. Given a target delta and structure (covered call or cash-secured put), it picks the best candidate and reports annualized yield, assignment probability, breakeven, and a roll candidate, while filtering or flagging picks whose expiry spans an earnings event.

It returns the standard strategy decision envelope shared by all Strategy Signals endpoints, so the score, decision, and best_structures shape match every other strategy. The yield-specific detail lives in metrics, and risk flags such as EARNINGS_BEFORE_EXPIRY and EX_DIVIDEND_RISK_NOT_MODELED appear in risk_flags where applicable.

Common Use Cases

• Drop in the proposed overlay - pull best_structures[] for a covered-call or cash-secured-put at a fixed target delta
• Trade only clean signals - act when decision is candidate and skip no_setup reads where the yield is thin
• Rank income across a watchlist - sort by score to surface the richest overlays for the risk taken
• Screen out event risk - drop picks where risk_flags[] flags an earnings event inside the tenor
• Size on conviction - scale the overlay by score and confidence rather than a fixed contract count
• Respect the guardrails - require a clean data_quality and read regime before writing premium, and surface a roll candidate as expiry approaches

Related

Research

The endpoint's own weekly picks were held to expiry over 2022-2025, with absolute delta compared against how often contracts finished in the money. A separate pack studies a fixed monthly covered-call and cash-secured-put rule, and a later study tests covered calls at six deltas and five expiries with this endpoint's decision as one of 11 filters.

• Does expiring gamma move the market? - results and method
• Research pack trader-context-spy-qqq-2022-2025-v2-34105d743fac - data, audit and reproduction (Alpha)
• Covered calls and cash-secured puts research pack - the fixed-rule income study
• Are covered calls worth it? - SPY and QQQ covered calls versus holding, 2022-2026, by delta and expiry

Related reading

• VRP strategy scoring: pick the right options structure - how the score selects the income overlay
• ML on options data: a quant guide - feed the yield envelope into a systematic model
• Alpha decay: which signals erode - how an income edge fades over time

Complementary endpoints

• Strategy Signals overview - the shared decision envelope across every strategy
• Vol Carry - confirm the carry edge that makes the overlay worth writing
• Term Structure - pick the tenor where the yield is richest