# Option Scanner API

Scan live and delayed option chains for trade candidates matching a strategy definition. The scanner powers the [Option Scanner](https://orats.com/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](https://orats.com/tools-apis).

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

---

## Scan

`POST https://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

- `v` (number): The API version, passed as a query parameter. Always 2.
- `backtest` (object): 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

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

**cURL**

```bash
curl -L "https://api.orats.io/scanner/scan?v=2&token=my-token" \
  -H "Authorization: my-token" \
  -H "Content-Type: application/json" \
  -d '{
    "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**

```json
[
  {
    "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
      }
    ]
  }
]
```