Unusual Options Activity Scanner 📈

Changelog

• 2026-07-29 — Reliability fix: runs launched via API/integrations with unset optional fields sent as null could fail outright instead of using the documented defaults. Fixed, covered by tests.

Give it a list of tickers and get the option contracts that are actually being traded today on abnormal volume — the fresh, big-money positioning that raw option chains bury.

What "unusual" means here

An option chain is thousands of rows. Almost all of it is noise. What matters is the handful of contracts where today's volume is far bigger than the open interest that was already there — that means new positions are being opened right now, not old ones being closed. Layer on the dollar premium behind the trade, and you get the same signal the "unusual options activity" services sell: where the smart money is quietly building.

This actor turns a raw chain into that signal. For each ticker it pulls the full chain, then keeps only the contracts that clear three gates at once:

1. Liquidity — traded at least min_volume contracts today.
2. Fresh positioning — today's volume is at least min_vol_oi_ratio× the standing open interest (contracts with no prior open interest qualify on volume alone).
3. Real money — estimated premium traded (volume × price × 100) is at least min_premium_usd.

What you get

Two kinds of rows in one dataset:

contract rows — each unusual contract found:

Field	Description
ticker	Underlying symbol
option_type	call or put
strike / expiry	Contract strike and expiration date
spot	Underlying price at scan time
moneyness	ITM / ATM / OTM relative to spot
volume	Contracts traded today
open_interest	Contracts outstanding before today
vol_oi_ratio	Volume ÷ open interest (how fresh the positioning is)
last_price	Last traded contract price
premium_usd	Estimated dollar premium traded (volume × price × 100)
implied_volatility	IV for the contract, when priced
unusual_score	Sortable blend of ratio and premium — biggest signals on top

sentiment rows — one summary per ticker: net call vs put premium across its unusual contracts, labelled BULLISH, BEARISH or MIXED. This is the headline read — is the unusual flow leaning up or down?

Rows are sorted with the strongest unusual_score first, and the per-ticker sentiment summaries are always included.

Nothing unusual = never billed. You only pay for runs that actually return signals.

Source & why it's deliberately slow

Data comes from CBOE's public delayed-quote feed — one login-free request per ticker returns the full chain with volume, open interest, implied volatility and Greeks. Because the data is end-of-session delayed, the scanner works 24/7, not only during US market hours.

This actor scrapes slowly on purpose: it spaces every request and backs off politely if the source pushes back, so it stays reliable on large watchlists rather than fast and brittle. A scan of a handful of tickers takes a few seconds; a big watchlist takes proportionally longer. That is by design — reliability over speed.

Use cases

• Smart-money tracking — see which strikes and expiries are getting unusual fresh flow.
• Sentiment at a glance — the per-ticker BULLISH/BEARISH read on option positioning.
• Watchlist monitoring — scan your names daily and log the standout contracts.
• Model inputs — feed unusual-flow signals into your own screening or alerts.
• Earnings & event runups — spot positioning building ahead of a catalyst.

Input

Field	Type	Default	Description
tickers	array	["AAPL","TSLA","NVDA","SPY","AMD"]	US stock/ETF symbols to scan
max_expiries	integer	3	Nearest expiration dates to scan per ticker
min_volume	integer	500	Ignore contracts trading below this many contracts today
min_vol_oi_ratio	number	2.0	Flag when volume ≥ this multiple of open interest
min_premium_usd	integer	50000	Only report contracts with at least this much premium traded
include_sentiment	boolean	true	Append a per-ticker call/put sentiment summary row
max_results	integer	100	Cap on unusual contracts returned (sentiment rows are always kept)
request_timeout_secs	integer	30	HTTP timeout in seconds

Example input

{
  "tickers": ["AAPL", "NVDA", "SPY"],
  "max_expiries": 2,
  "min_volume": 500,
  "min_vol_oi_ratio": 2.0,
  "min_premium_usd": 50000
}

Example output

{
  "row_type": "contract",
  "ticker": "SPY",
  "option_type": "put",
  "strike": 751.0,
  "expiry": "2026-07-10",
  "spot": 751.71,
  "moneyness": "ATM",
  "volume": 101234,
  "open_interest": 2492,
  "vol_oi_ratio": 40.62,
  "last_price": 1.39,
  "premium_usd": 14071526.0,
  "implied_volatility": 11.19,
  "unusual_score": 47.35
}

{
  "row_type": "sentiment",
  "ticker": "NVDA",
  "sentiment": "BULLISH",
  "call_premium_usd": 156450000.0,
  "put_premium_usd": 45480000.0,
  "call_share": 0.775,
  "unusual_contracts": 22,
  "premium_usd": 201934426.0
}

Tips

• Start with the defaults, then raise min_premium_usd to focus only on the biggest prints.
• Lower min_vol_oi_ratio toward 1.0 for wider coverage, raise it for only the freshest positioning.
• A high vol_oi_ratio on a contract with near-zero open interest is the classic "brand-new position" tell.
• Widen max_expiries to catch positioning further out (earnings, macro events).

Disclaimer

This actor returns delayed public market data for informational purposes only. It is not financial, investment or trading advice. "Unusual" volume is a mechanical signal, not a prediction — large prints can be hedges, spreads, or closing trades, and premium is an estimate from last price, not a confirmed fill. Always do your own research. You are responsible for your own decisions and for complying with CBOE's terms and your local laws.