Metric evaluation & risk flags

From a filtered option chain the evaluation service computes a metric (score) for each contract and sorts the candidates by it. Each candidate is additionally annotated with risk flags. The sorting is a neutral aid for overview – not a buy or sell signal and not a selection recommendation.

Annualized premium

annualized_premium_pct = (mid / strike) * (365 / dte) * 100

Example: AAPL put 180, mid 2.10, DTE 30 → (2.10 / 180) * (365 / 30) * 100 = 14.2 % p.a.

Sorting by metric

Candidates are sorted by their metric in descending order and shown as a list. Sorting happens after DTE / delta / OI / volume filters are applied. You may optionally exclude strikes carrying certain risk flags (exclude_flags). Which contracts appear and in which order is controlled solely by your filter and sorting settings.

Risk flags

Default earnings window: 7 days before expiry.

Configuration

POST /api/options/medals/{SYMBOL}
{
  "expiry": "2026-06-19",
  "filters": { "option_type": "PUT", "dte_min": 7, "dte_max": 60 },
  "top_n": 3,
  "earnings_window_days": 7,
  "exclude_flags": ["earnings", "iv_extreme"]
}

The response carries per candidate: the contract, annualized_premium_pct and risk_flags: [].

Quick view (candidates across all expiries)

The company detail page (/research/companies/{SYMBOL}) uses an endpoint that scans every expiry inside your strategy DTE range (UserSettings.min_dte / max_dte) in a single round-trip and returns one bucket per allowed Wheel strategy (PUT-L1 if you hold no shares, PUT-L2 if you do, plus CC when shares are free for assignment).

POST /api/options/medals-best/{SYMBOL}
{
  "top_n": 3,
  "earnings_window_days": 7,
  "min_open_interest": 0,
  "dte_min": null,   // optional override, otherwise from UserSettings
  "dte_max": null
}

The filter pipeline is identical to the cross-symbol Wheel screener (moneyness_pct=0.15, iv_extreme excluded, min ROC + strike-above-cost from your filter settings, sanity cap 200 % p.a.). Candidates can come from different expiries; each card shows its own expiry.

Reading the list

In the chain page the candidates are shown as cards on top, each with the metric, premium p.a., strike, DTE, mid, delta, IV, OI – plus the colored flag chips below.

The ATR value on a card is the ATR distance (strike distance to spot in ATR52 units), shown as e.g. 1.38× ATR – not the raw ATR52, which is a USD amount shown in the header as "ATR(52) … USD". The mid is displayed with three decimals; returns always use the unrounded mid.

Score model (detail)

The full description of the pipeline (filters → score → sorting), all sub-score weights, the target_return table, the cost_basis logic and the thresholds lives in its own topic "Scoring model (PUT L1/L2, CC)".

Short version below:

The metric uses the same scoring as the desktop app (file services/option_scoring.py, ported 1:1 from app/utils/option_utils.py). A strike is evaluated by several sub-scores; the sum is the metric used for sorting.

PUT (max 110)

`target_return` depends on the PUT strategy:

L2 demands a lower yield because the additional put primarily serves cost-basis reduction – not building a new position. Identical strikes therefore get a higher metric when has_stock=True.

ATR distance for puts is always measured against the current price:

atr_distance_put = (current_price - strike) / atr52

Why: when selling a put you do not yet own the shares – the strike is the future assignment price. The distance measures the safety cushion relative to the current price.

Covered call (max 100)

Important: for the CC the reference is your cost basis, not the current price. You already own shares and want the call to be exercised above your entry. Both ATR distance and capital gain are computed against cost_basis:

reference        = cost_basis if (has_stock and cost_basis > 0) else current_price
atr_distance     = (strike - reference) / atr52
capital_gain_pct = (strike - reference) / reference * 100

Example CMG, cost_basis 34.00, current price 36.20, ATR52 1.31:

This is why CC strikes that would have a lower metric vs. spot can still surface when you hold the underlying.

Where has_stock and cost_basis come from

The load_symbol_context service inspects your open long-stock positions for the symbol. If found, has_stock=True and the average entry price are passed to the evaluator as purchase_price.

Related

• "Options screening" (which filters exist)
• "Smart-limit & mid-drift" (how a candidate becomes a proposal with a limit)
• "Safety gates" (what is checked before sending)

Legal note

The metric is an algorithmic sorting aid. Not a buy signal, not a sell signal, not investment advice, not a recommendation. It does not replace your own review of market data and news on the underlying company.