Options Leg

The options leg filters stocks by how the options market is positioned around them — implied volatility levels, put/call skew, positioning direction, and unusual activity.

options leg shape

"options": {
  "pattern":      "bullish_positioning",
  "horizon":      "long",
  "min_strength": 0.6
}

:::info US-listed optionable stocks only Covers approximately ~557 US-listed optionable names. Non-US stocks are excluded from this leg — they can't match and don't reduce the overall result count. :::

---

Fields

Field	Type	Required	Description
pattern	string (enum)	✅	Options-behaviour pattern. See full enum below.
horizon	"short" | "long"	—	Which horizon to read. "long" (default) = longer-dated positioning / conviction lens. "short" = near-term gamma / expiry lens.
min_strength	number (0–1)	—	Minimum signal strength. Omit to return all matches, ranked by strength descending.

---

pattern enum

These are the valid values for pattern. The supported column shows availability:

• yes — live, use freely
• approx — live but based on a proxy metric; results are directionally correct
• future — planned, not yet live (returns 400 if used)

Implied Volatility

pattern	Label	Supported	What it detects
iv_cheap	IV cheap	yes	Implied vol at the low end of its own 1-year history — options are inexpensive relative to the stock's own past
iv_rich	IV rich	yes	Implied vol at the high end of its own history — options are expensive
iv_crush	IV crush (post-event)	future	IV collapsing fast after an earnings/event (planned)

Positioning Direction

pattern	Label	Supported	What it detects
bullish_positioning	Bullish positioning	yes	Options crowd leaning bullish — positioning score elevated, calls heavier than puts
bearish_positioning	Bearish positioning	yes	Options crowd leaning bearish — puts heavier, positioning score depressed
crowded_one_sided	Crowded / one-sided	yes	Extreme one-sided positioning either direction — elevated unwind or squeeze risk
divided_opinion	Divided opinion	approx	Positioning near zero but activity high — the crowd is split on direction

Sentiment & Skew

pattern	Label	Supported	What it detects
fear_building	Fear building	yes	Put skew unusually elevated vs own history — the market is pricing downside protection
greed_euphoria	Greed / euphoria	yes	Call skew rich — traders paying up for upside; sentiment running hot
event_premium	Event / catalyst premium	approx	Options pricing an upcoming dated catalyst (earnings, FDA, macro)

Positioning Shifts

pattern	Label	Supported	What it detects
positioning_flip	Positioning flip	approx	Positioning reversed sharply vs prior session — a crowd change in progress
distrust_short_believe_long	Distrust short / believe long	yes	Short-term bearish but long-term bullish positioning — market doubts near-term but believes in the thesis
believe_short_distrust_long	Believe short / distrust long	yes	Short-term bullish but long-term bearish — tactical bounce, not conviction

Structure & Activity

pattern	Label	Supported	What it detects
unusual_activity	Unusual options activity	yes	Option volume unusually high vs own history — informed flow or catalyst speculation
short_gamma_unstable	Short-gamma / unstable	yes	Dealers net short gamma — moves get amplified in both directions; watch for sharp intraday swings
pinned_max_pain	Pinned to max-pain	yes	Spot price near max-pain level heading into expiry — pinning effect expected

Divergence

pattern	Label	Supported	What it detects
options_vs_price_divergence	Options vs price divergence	approx	Options positioning moving opposite to the price trend — smart money disagreeing with price
options_vs_news_divergence	Options vs news divergence	future	Options positioning opposite to news sentiment (planned)

---

horizon

Value	What it reads
"long" (default)	Longer-dated options (weeks–months) — positioning and conviction lens
"short"	Near-term options (days–1 week) — gamma, pinning, and expiry dynamics

For short_gamma_unstable and pinned_max_pain, always use "horizon": "short". For positioning patterns (bullish_positioning, fear_building, etc.), "long" is usually more meaningful.

---

min_strength

Strength is a 0–1 score measuring how strongly the signal is firing relative to the stock's own history:

Range	Interpretation
0.8–1.0	Strong, clear signal
0.5–0.8	Moderate signal
0.3–0.5	Weak / marginal
< 0.3	Noise

Omit min_strength to see all matches ranked by strength — useful for exploration. Set 0.6+ in production to avoid noise.

---

Examples

Options crowd bullish — US large-caps sorted by signal strength

{
  "universe": { "include": [{ "country": ["US"], "size": ["large","mega"] }] },
  "options": { "pattern": "bullish_positioning", "horizon": "long" },
  "sort": "options",
  "limit": 20
}

IV cheap + price near 52-week high (breakout with cheap options)

{
  "ta": [{ "anchor": [{ "pattern": "near_52w_high", "b": "0.05" }] }],
  "options": { "pattern": "iv_cheap", "min_strength": 0.5 }
}

Fear building — combine with oversold TA for contrarian entry

{
  "universe": { "include": [{ "country": ["US"] }] },
  "ta": [{ "anchor": [{ "pattern": "oversold", "a": "rsi14" }] }],
  "options": { "pattern": "fear_building", "horizon": "long", "min_strength": 0.6 }
}

Unusual activity — smart money flow alert

{
  "universe": { "include": [{ "country": ["US"] }] },
  "options": { "pattern": "unusual_activity", "min_strength": 0.7 },
  "sort": "options"
}

Short-gamma instability — watch for amplified moves

{
  "universe": { "include": [{ "country": ["US"], "size": ["large","mega"] }] },
  "options": { "pattern": "short_gamma_unstable", "horizon": "short" },
  "sort": "options"
}

Positioning flip — crowd just changed direction

{
  "universe": { "include": [{ "country": ["US"] }] },
  "options": { "pattern": "positioning_flip", "horizon": "long", "min_strength": 0.5 }
}