Option Scanner API

View as Markdown

Scan live and delayed option chains for trade candidates matching a strategy definition. The scanner powers the Option Scanner in the ORATS dashboard and returns candidates with pricing, greeks, probability of profit, and risk metrics.

Authenticate with an Authorization header containing the raw token, with no Bearer prefix. Requests without the header return a 401. The token query parameter is optional; when present it is validated instead of the header value, so if you send both, use the same token in each.

All responses are in JSON format. The response is an array of candidate objects, one per trade candidate.

Product overview and pricing for this and the other Tools APIs live on the Tools APIs page.

Base URL:https://api.orats.io/scanner

Scan

POSThttps://api.orats.io/scanner/scan

Scans the current option chain for trade candidates matching a strategy definition and returns them ranked with pricing, greeks, and distribution analytics.

The scan always uses the most recent chain. Symbols with no options data return an empty array rather than an error.

Required attributes

Name
v
Type
number
Description
The API version, passed as a query parameter. Always 2.
Name
backtest
Type
object
Description
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.
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 of type absDelta with a delta band (target, min, max). Leg relationships such as strike width and DTE difference can be constrained via entry.legRelation.
See the request example for a complete single-leg definition.

Optional attributes

Name
totalTrades
Type
number
Description
The maximum number of candidates to return across all symbols. Defaults to 1.
Name
tradesPerSymbol
Type
number
Description
The maximum number of candidates to return per symbol. Defaults to 1.
Name
dataSource
Type
string
Description
The quote feed to scan: real-time or delayed. Ex: delayed
Name
distribution
Type
boolean
Description
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.
Name
drift
Type
number
Description
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. Ex: 10
Name
id
Type
string
Description
A label for the scan, echoed for bookkeeping. Not validated. Ex: LongCall

POST/scanner/scan

{
  "backtest": {
    "general": {
      "strategyName": "LongCall",
      "expirationType": "ALL",
      "stockPosition": {
        "type": "none",
        "ratio": 0
      },
      "symbols": [
        {
          "weight": null,
          "signals": null,
          "symbol": "AAPL"
        }
      ],
      "returnType": {
        "perTrade": "notional",
        "daily": "average"
      },
      "commission": {
        "option": 1,
        "stock": 0.01
      }
    },
    "entry": {
      "options": [
        {
          "ratio": 1,
          "optionType": "call",
          "leg": 1,
          "opening": {
            "dte": {
              "target": 30,
              "min": 20,
              "max": 45
            },
            "strikeSelection": {
              "type": "absDelta",
              "value": {
                "target": 0.3,
                "min": 0.2,
                "max": 0.5
              }
            }
          }
        }
      ]
    },
    "exit": {
      "dteDays": "expire"
    }
  },
  "totalTrades": 20,
  "tradesPerSymbol": 10,
  "dataSource": "delayed",
  "distribution": true,
  "drift": 0,
  "id": "LongCall"
}

Response

[
  {
    "date": "2026-07-15",
    "ticker": "AAPL",
    "stockPrice": 327.33,
    "bid": 4,
    "mid": 4.2,
    "ask": 4.4,
    "iv": 27.6,
    "distPct": -31.65,
    "fcstPct": 4.02,
    "smoothPct": 0.24,
    "delta": 0.27,
    "gamma": 0.01326,
    "theta": -0.15,
    "vega": 0.3189,
    "deltaCost": 0.03166,
    "risk": 10.8985132,
    "maxGain": 4577.38,
    "maxLoss": -420,
    "pop": 17.82,
    "breakEvens": [
      349.2
    ],
    "earningsDate": "2026-07-30",
    "lastEarningsDate": "2026-04-30",
    "earningsTimeOfDay": "1630",
    "earningsConfirmed": 1,
    "divDate": "2026-08-11",
    "divAmt": 0.27,
    "legs": [
      {
        "leg": 1,
        "ratio": 1,
        "optionType": "call",
        "expirDate": "2026-08-14",
        "strike": 345,
        "expiryTod": "pm",
        "dte": 31,
        "optionBid": 4,
        "optionAsk": 4.4,
        "tradeOptPx": 4.3,
        "theoOptPx": 4.21,
        "fcstOptPx": 4.3688,
        "iVolBid": 0.2667,
        "iVolAsk": 0.2797,
        "tradeVol": 27.6,
        "theoVol": 27.4,
        "fcstRatio": 1.02,
        "delta": 0.27,
        "gamma": 0.01326,
        "vega": 0.3189,
        "theta": -0.15,
        "volume": 598,
        "openInterest": 998,
        "calVol": 28.42,
        "unadjVol": 24.11,
        "deltaCost": 0.03166,
        "updatedAt": "2026-07-15T19:59:49Z",
        "distValue": 2.8708215979740945
      }
    ]
  }
]