/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`](../options-flow). For the book-level risk that motivates the hedge, use [`risk-report`](../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`](./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`](./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`](./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`](../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/