Option Scanner API

The API version, passed as a query parameter. Always 2.

The strategy definition to scan with, passed in the JSON body.

Set the symbols to scan in general.symbols, one entry per symbol with weight and signals set to null. Response time scales with the number of symbols.

general.expirationType filters which listed expirations each leg may use, and applies per leg on both single- and multi-leg scans. ALL (also the behavior when the field is omitted or null, and the value in every request example here) keeps every listed expiration. MONTHLY keeps expirations on the third Friday of the month, or the Thursday immediately before it when that Friday is not listed for the ticker (the holiday-shifted monthly). WEEKLY keeps every listed expiration that is not a monthly by that rule. Values are case-insensitive and normalized to uppercase; anything else returns a 400 naming the field and the three choices.

Define one leg per entry.options entry: ratio (negative for short legs), optionType (call or put), leg (1-based), an opening.dte band of days to expiration (target, min, max), and an opening.strikeSelection with a band (target, min, max). The strikeSelection type is absDelta (the band is absolute delta), stockOTMPct (the band is strike divided by stock price, so 1.03 to 1.10 selects calls 3 to 10 percent out of the money and values below 1 select out-of-the-money puts), or both, which keeps a contract inside either band and takes a value whose min and max are objects holding an absDelta and a stockOTMPct number, with a single numeric target that is scored against both the absolute delta and the strike-to-stock ratio (the flat value shape, a nested target, or a missing target returns a 400). The type is case-sensitive and any other spelling returns a 400. optionType must be call or put, ratio a nonzero number, and legs numbered 1 to N in order; each of those returns a 400 naming the leg otherwise. Symbols are trimmed and upper-cased, and share classes may be written BRK_B, BRK.B, or BRK/B.

Multi-leg definitions also require entry.legRelation, keyed by leg pair: for example entry.legRelation.strikeWidth.leg1Leg2 with min and max in strike points, and entry.legRelation.dteDiff.leg1Leg2 with min and max in days (0,0 forces the same expiration). The relation properties are strikeWidth (strike points), dteDiff (days), and deltaTotal (the ratio-weighted net delta of the pair); any other key under legRelation, or a leg pair that does not exist for the leg count, returns a 400 when it has non-null values (all-null placeholders are accepted). Spread-level price, delta, and yield bands go in entry.spread as min and max objects, with an optional target that is scored against the assembled spread. A body that is not valid JSON returns a 400 with the message "payload format error."; a multi-leg definition without entry.legRelation, a leg without opening or opening.dte, a missing general or entry block, or a symbols entry without a string symbol returns a 400 with a message naming the problem; so does a leg without a strikeSelection.value, a strike, DTE, or spread band whose min exceeds its max or whose target lies outside it, and a body without a backtest object (backtest input is required.). legRelation bands are validated the same way: an inverted or non-numeric strikeWidth, dteDiff, or deltaTotal band, or a band written as an array instead of a min and max object, returns a 400 naming the pair; a band that is valid but that no contract in the leg pools can satisfy still returns an empty array.

See the request example for a complete single-leg definition.

The maximum number of candidates across all symbols. Applied only when tradesPerSymbol is 0 or null; otherwise tradesPerSymbol alone sets the response size. Must be a non-negative integer. Defaults to 10.

The maximum number of candidates to return per symbol (not capped). For multi-leg definitions it also sets how many candidate contracts each leg keeps before the legs are paired: the closest tradesPerSymbol divided by the leg count contracts to that leg's targets, whatever the strategyName. Because pairing happens inside those pools, a low tradesPerSymbol can return an empty array even though matching spreads exist; use 20 to 100 for two legs and at least 40 for four. Must be a non-negative integer (a numeric string is accepted); a fraction, a negative, or a non-numeric value returns a 400. Defaults to 1.

The quote feed to scan: real-time or delayed (the 15-minute feed). real-time, realtime, and delayed are accepted in any letter case; any other value returns a 400. Real-time quotes are live OPRA data, so they need the same live data entitlement (signed OPRA agreements) as the live endpoints; without it a real-time scan returns a 403. Each leg's updatedAt is the quote time. Ex: delayed

Whether to include distribution analytics. When true, each candidate includes risk, maxGain, maxLoss, pop, and breakEvens, distPct is populated, and each leg includes distValue. Recommended: true.

The assumed stock drift in percent, for probability of profit. 0 is neutral; positive is a bullish outlook, negative is bearish. Drift changes pop, distPct, and each leg's distValue; values beyond roughly plus or minus 20 saturate pop at 100 or 0, and a value outside -100 to 100 or a non-numeric value returns a 400. Ex: 10

A label for the scan. Not validated and not echoed in the response (which is an array of candidates with no wrapper object). Ex: LongCall

The scan's business date, the underlying, and the underlying price at the first leg's quote.

The structure's net price from the legs' quotes; mid is the true midpoint. Credit structures are negative (mid is minus the credit received), so bid is greater than ask with that sign convention.

Ratio-weighted average of the legs' tradeVol, in percent.

Percent edge of the distribution value, the forecast-volatility price, and the smoothed theoretical price over mid. distPct is null without distribution.

Ratio-weighted sums of the per-leg greeks (per share) and of deltaCost.

Present with distribution true. maxGain and maxLoss are dollars per one-lot at mid, evaluated across the plus or minus three sigma price range, so unbounded payoffs are bounded there; risk is maxGain divided by the absolute maxLoss; pop is the percent probability of profit at expiration on a 21-bucket terminal distribution (profit zones narrower than about 0.3 sigma, such as butterflies, produce a pop near zero), null for legs with a ratio other than plus or minus one; breakEvens is an array of underlying prices, empty for calendars.

Next and last earnings dates, the earnings time as HHMM, whether the date is confirmed (0 or 1), and the next ex-dividend date and amount. Null for ETFs and indexes.

The contract. expiryTod is am or pm settlement; dte counts today's expiration as 1.

The raw quote, the assumed fill (long legs at bid plus a fraction of the spread, short legs at ask minus it; the fraction is 0.75 for one leg, 0.66 for two, 0.56 for three, 0.53 for four or more), the ORATS smoothed theoretical value, the forecast-volatility value, and fcstOptPx divided by tradeOptPx.

Implied volatilities: iVolBid and iVolAsk are decimals; tradeVol (at the fill), theoVol (smoothed), calVol (including the earnings effect), and unadjVol (ex-earnings) are percent.

Per-share greeks (put deltas negative), the side's volume and open interest, premium per unit of delta, volatility, and time (tradeOptPx divided by the absolute delta times stock price times tradeVol times the square root of dte, times ratio times 100), the quote time in UTC, and the leg's expected value under the drift-adjusted distribution (with distribution true).