Options & Positioning Tools
These tools answer questions like:
- "What is the options market saying about NVDA?"
- "Which stocks is the crowd getting scared of right now?"
- "Where is futures positioning most stretched — what's a crowded trade?"
- "Find stocks where smart money is quietly building a bullish position"
- "Is copper futures positioning already priced-in bullish?"
Tools at a glance
| Tool | What it does | Coverage |
|---|---|---|
options_sentiment | Full options positioning read for one stock, or a batch comparison | ~557 US-optionable names |
find_oppattern | Resolve a plain-language options-behavior phrase to a scan token | — |
options_scan | Scan all US optionable names for a specific options-behavior pattern | ~557 US names |
positioning | COT futures positioning for one commodity/FX/rate/index asset | CFTC-tracked assets |
cot_extremes | Most crowded COT positions across all tracked markets | All CFTC markets |
options_sentiment — What the options market says about a stock
Returns what the US options market is pricing in for one stock: put/call lean, implied volatility percentile, dealer gamma stability, max-pain pinning, and notable expiries — with plain-language read labels for each signal.
Single stock (deep read)
Pass ticker for a full narrative payload with per-horizon breakdowns and a _guide that tells the AI exactly how to narrate each signal to a non-expert.
options_sentiment(ticker="NVDA.US")
options_sentiment(ticker="TSLA.US", as_of="2026-06-30") # historical
Batch comparison
Pass tickers=[...] (and optionally dates=[...]) for a compact comparison grid — one row per ticker × date cell. This is how you answer "NVDA vs AAPL, last week vs this week" without N×M calls.
options_sentiment(
tickers=["NVDA.US", "AAPL.US", "TSLA.US"],
dates=["2026-07-31", "2026-08-29"]
)
Key params:
| Param | Description |
|---|---|
ticker | A US-optionable ticker (NVDA / NVDA.US) or index-ETF proxy (SPY, QQQ, GLD) |
style | plain (default, layperson language) or technical |
as_of | ISO date for historical point-in-time snapshot |
tickers | Batch form — list of tickers |
dates | Batch form — list of ISO dates |
If a ticker is not covered (covered: false), the response says so — never fabricate a positioning read; use the news/impact lens instead.
:::tip Index proxies
For a broad-market positioning read: S&P 500 → SPY, Nasdaq 100 → QQQ, Dow → DIA, Russell 2000 → IWM, 20y Treasuries → TLT, Gold → GLD.
:::
find_oppattern — Resolve an options-behavior phrase
Translates plain-language descriptions of options-market behavior into the exact pattern tokens that options_scan and screen_unified's options leg expect.
Tense matters — the temporal mode is a real axis: "the crowd is afraid" (state NOW) vs "fear is building" (trend) vs "was afraid, now getting brave" (flip) resolve to different tokens.
Example inputs → what comes back:
| Input | Pattern token | Temporal mode |
|---|---|---|
"crowd is scared" | fear_level | level |
"fear is building" | fear_building | rising |
"was scared, now braver" | fear_to_confidence | flip |
"smart money buying" | positioning_building_bull | rising |
"IV cheap" | iv_cheap | level |
"one-sided / crowded" | crowded_bull or crowded_bear | level |
The response also tells you the exec_path:
scan→ feed the pattern token tooptions_scancompose→ the pattern needs composing with another leg (e.g. a price-trend divergence); the response includes acompose_recipeunsupported→ no such data available; say so plainly
This resolver is free (0 credits).
options_scan — Scan the universe for an options pattern
Finds stocks across the ~557 US optionable names that match an options-behavior pattern — ranked, each with a plain-language because explanation and the underlying metrics.
options_scan(pattern="fear_building")
options_scan(pattern="iv_cheap,positioning_building_bull") # AND-combine with CSV
The pattern token comes from find_oppattern. Multiple tokens in a CSV are AND-combined; the first token owns the ranking.
Key params: horizon (long = conviction/positioning lens, short = gamma/near-term), min_strength, limit (default 15).
:::note US only
options_scan covers ~557 US-optionable names only. For non-US stocks, options data isn't available — say so and use the news/impact lens instead.
Options history window is ~1 month. Older-period questions ("fearful in May") aren't supported. :::
positioning — COT futures positioning
CFTC Commitment of Traders (COT) futures positioning for a single commodity, FX pair, rate, or equity index. Returns the current net positioning percentile for commercials (the "smart money"), large speculators, and small speculators — plus a historical series.
This is the non-equity equivalent of options_sentiment — for assets that don't have an options market but do have CFTC futures data.
Ticker formats:
| Asset class | Format | Examples |
|---|---|---|
| Commodities | SYMBOL.COMM | COPPER.COMM, GOLD.COMM, WTI.COMM |
| FX | PAIR.FOREX | EURUSD.FOREX, USDJPY.FOREX |
| Government bonds | ISO2-TENOR.GB | US-10Y.GB, JP-10Y.GB |
| Equity indices | TICKER.US | SPY.US, QQQ.US |
:::caution Bond positioning is inverted
For .GB and .MM assets, long futures = positioned for lower yields (i.e. bullish on the bond price). The tool accounts for this inversion automatically, but keep it in mind when narrating.
:::
cot_extremes — Where positioning is most stretched
Returns assets with the most extreme COT positioning — near historical highs or lows for any spec group. Useful for identifying crowded trades and potential mean-reversion setups.
cot_extremes(asset_class="commodity") # most crowded commodity positions
cot_extremes(limit=20) # top 20 across all markets
Key params: asset_class (filter to commodity, forex, rates, equity), limit (default 15).
Pair with news for the full picture
Options/COT positioning answers how the market is positioned but not why. The most informative reads pair positioning with news:
| Combination | Insight |
|---|---|
| Bullish news + bullish positioning | Good news may be priced in — upside limited |
| Bullish news + bearish positioning | Positioning hasn't caught up — potential catch-up move |
| Bearish news + bullish crowded positioning | Unwind risk — position is fragile |
Use asset_pulse (stocks/ETFs) or commodity_pulse (commodities) to get both lenses in one call.
Routing guide
| You want to… | Use |
|---|---|
| "What is the options market saying about NVDA?" | options_sentiment(ticker="NVDA.US") |
| "NVDA vs AAPL positioning, last 2 quarters" | options_sentiment(tickers=[...], dates=[...]) |
| "Find stocks the crowd is getting scared of" | find_oppattern → options_scan |
| "Add an options condition to a screener" | find_oppattern → screen_unified(options=...) |
| "Is copper futures positioning crowded?" | positioning(asset="COPPER.COMM") |
| "What's the most crowded commodity trade?" | cot_extremes(asset_class="commodity") |