hedge-suggester

name

hedge-suggester

description

Proposes concrete, live-priced option hedges against a single long position and ranks them by cost per dollar of downside protected. Takes a ticker and a position size (shares or notional), pulls the underlying price and the options chain around the horizon expiry, and constructs five standard overlays (covered call, protective put, collar, put spread, ratio put spread) priced from chain mids with net cost, breakeven, max loss, max gain, and net delta/gamma/theta at open. The take line recommends the structure that fits the stated risk tolerance. Use when a concentrated long needs a hedge and you want the actual structures and their live cost, not just "you are over-exposed." Needs Stocks Starter plus the Options Developer add-on. Not advice.

hedge-suggester

risk-report tells you that ALLO is carrying most of your book's variance. options-flow tells you what other traders are doing on ALLO. Neither one tells you what to actually do about it. hedge-suggester closes that loop: you hand it the position, it hands back concrete option overlays, each one priced live off the chain and ranked by how cheaply it buys downside protection.

This is the "so what do I do" layer. It does not forecast the stock and it does not give advice. It prices the standard hedges a desk would reach for against a long, states each one's cost and payoff bounds honestly, and recommends the one that matches the risk tolerance you state.

When to invoke

• risk-report or a concentration check has flagged a single long as the dominant risk in a book, and the next question is "how do I hedge it"
• A PM holds a large single-name long into an uncertain window (a horizon of weeks) and wants the actual protective structures priced
• The user says "hedge my ALLO", "how much would a collar on NVDA cost", "what's the cheapest downside protection on this position", "protect my gains without selling", "put spread vs protective put on TSLA"
• You want the concrete follow-through to options-flow or risk-report rather than another read-only diagnostic

For what other traders are doing on the name, use options-flow. For the book-level risk that motivates the hedge, use risk-report. For how the hedged book behaves under macro shocks, chain into portfolio-macro-scenario.

What you need

• --ticker (required): the underlying of the long position
• --shares OR --notional: the position size (notional is converted to shares at spot)
• MASSIVE_API_KEY exported in the environment
• Stocks Starter (underlying snapshot and daily aggregates) plus the Options Developer add-on (options chain snapshot with bid/ask, open interest, implied vol, and greeks). This is the same options entitlement options-flow needs.

Optional:

• --risk-tolerance (low / medium / high, default medium): drives which structure the take line recommends
• --horizon-days (default 45): protection horizon; the chosen expiry is the nearest listed expiry at or beyond this
• --sleep (default 0): seconds between aggregate calls; use --sleep 13 on a rate-limited key
• --format (render / json / both)

What you get back

Two output layers from one run.

Layer 1: canonical JSON matching output-schema.json. Per-structure legs, net_cost_usd (debit positive / credit negative), breakeven, max_loss_usd, max_gain_usd, protection_floor / protection_ceiling / upside_cap, downside_protected_usd, cost_per_dollar_protected, and net_delta / net_gamma / net_theta at open, plus a ranking, an iv_context block, and the composed take. UIs and downstream agents consume this.

Layer 2: rendered table: the structures sorted cheapest-insurance-first, then per-structure legs, greeks, tradeoff, and caveats, then the take. See references/rendering.md.

How it works

1. Resolve spot via /v2/snapshot/locale/us/markets/stocks/tickers/{T} and the shared best-price fallback chain. Size the position into shares and round-lot contracts.
2. Pull the chain around the horizon expiry via /v3/snapshot/options/{T} filtered to a strike band and an expiry window, then pick the nearest listed expiry at or beyond the horizon. Read bid/ask, open interest, implied vol, and greeks per contract (the same endpoint and fields options-flow uses).
3. Construct and price five structures against the long from chain mids. The structure definitions and payoff math are in references/methodology.md.
4. Rank by cost per dollar of downside protected (cheaper ranks higher) and label the tradeoff.
5. Caveat every structure (liquidity floors, tail risk) and the run (delayed tape, mid-price optimism, earnings not fetched, assignment / early-exercise, IV-vs-realized context).
6. Compose the take: recommend the structure that fits the stated risk tolerance, with its cost and protection, and a not-advice disclaimer.

Foundations used

• massive-api-patterns for REST auth, rate-limit handling, the best-price fallback chain for spot, and the /v2/aggs daily endpoint conventions.

Output mode: table

The deliverable is a set of structures compared on the same fields (cost, breakeven, max loss, max gain, protection), which is a table. The take line sits under the table as the one-line recommendation. A stream would lose the side-by-side comparison that is the whole point.

Endpoints used

• GET /v2/snapshot/locale/us/markets/stocks/tickers/{ticker}: underlying spot with the best-price fallback chain.
• GET /v3/snapshot/options/{ticker}: options chain snapshot with per-contract bid/ask (last_quote), open interest, implied vol, and greeks (delta/gamma/theta). Filtered by expiration_date and strike_price.
• GET /v2/aggs/ticker/{ticker}/range/1/day/{from}/{to}: underlying daily closes for the realized-vol / IV-context proxy. Pulled with the rate-limit-aware pattern.

Doesn't handle (yet)

• Earnings proximity. The run does not fetch the earnings calendar; it says so and tells the reader to check whether an earnings date falls before the expiry. A Benzinga-earnings pull would close this; queued.
• True IV percentile. The IV context is a proxy (ATM IV vs 20-day realized vol), not a percentile of the stock's own historical IV, which needs a historical IV series. Queued.
• Multi-expiry / calendar structures. One expiry per run. Diagonals and calendars are a clean extension.
• Optimal strike search. Strikes are picked at fixed moneyness targets (5% OTM call, ATM put, 10%/15% OTM short puts), not solved for a target cost or delta. A solver is a v2 candidate.
• Live fills. Everything is priced at chain mids; real fills cross the spread. The output flags this loudly rather than pretending otherwise.

These are clean PR extensions. The output schema is forward-compatible.

Not advice

This skill proposes structures and prices them from live data. It does not know your tax situation, your mandate, your existing options, or your view on the stock. Mid-price fills are optimistic, greeks are point-in-time, short legs carry assignment and early-exercise risk, and the ratio put spread carries real tail risk that the output flags explicitly. Treat the output as a costed menu, not a recommendation to trade.