Skip to content
TotalFinance

Strategies · @insiderfinance/totalfinance

@insiderfinance/totalfinance/strategy/scanner

import { … } from '@insiderfinance/totalfinance/strategy/scanner'
stable-by-law (pre-1.0; not a 1.0 stability guarantee)const 1iface 4type 2fn 1JSON ↗
const

SCAN_OBJECTIVES

#

Every ranking objective a scan accepts, as DATA — the single source the type, the runtime guard and the error message are all derived from.

RV11 — these were three copies: a hand-written union here, a hand-written array in optimizer.ts, and a third hand-written list inside the error string. The string copy drifted and kept teaching pop|ev after both were renamed, because plain prose is invisible to a rename of the quoted literals. One tuple, and .join(', ') for the message, is what makes that impossible rather than merely fixed.

'return' became 'returnOnRisk' in the same pass: it ranked by returnOnRisk and the candidate output already called that number returnOnRisk, so one quantity carried two public names.

Signature
import { SCAN_OBJECTIVES } from '@insiderfinance/totalfinance/strategy/scanner';

export declare const SCAN_OBJECTIVES: readonly ['probabilityOfProfit', 'expectedValue', 'returnOnRisk', 'expectedValuePerRisk'];

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

iface

ScanCandidate

#

Public declaration. Read the signature and member contracts below; no additional behaviour is inferred.

Signature
import type { ScanCandidate } from '@insiderfinance/totalfinance/strategy/scanner';

export interface ScanCandidate {
    structure: ScanStructure;
    /** The structure's strikes, ascending. */
    strikes: number[];
    /** Net debit (> 0 paid) or credit (< 0 received), PER CONTRACT (multiplier-scaled, 100×) — the
     * same units as `maxProfit`/`maxLoss`/`expectedValue` and `Position.netDebit()`. */
    netDebit: number;
    /** Max profit / max loss / expected value are per contract (100× multiplier, as in `Position`). */
    maxProfit: number | null;
    maxLoss: number | null;
    /** Whether each tail of the expiration payoff is bounded (a `null` bound above is unbounded). */
    bounded: {
        profit: boolean;
        loss: boolean;
    };
    breakevens: number[];
    probabilityOfProfit: number;
    expectedValue: number;
    /**
     * `|maxProfit / maxLoss|` — the same definition as `Position.probability().riskReward` — or
     * `null` when undefined (an unbounded side or a zero max loss). Never `Infinity` (B3).
     */
    returnOnRisk: number | null;
    /** `expectedValue / |maxLoss|` — a risk-normalized EV; 0 when risk is unbounded. */
    expectedValuePerRisk: number;
    /** Liquidity in `[0, 1]` from the legs' relative bid/ask spreads (1 = tight), null if unpriced. */
    liquidity: number | null;
    /** The value of the ranking objective for this candidate; `null` when the objective is undefined for it. */
    score: number | null;
    /**
     * The resolved legs (premiums included, whatever their source), so every candidate is
     * MATERIALIZABLE (WS7.3): `strategy(candidate.legs)` reconstructs the exact position for charting or
     * mark-to-market, and `strategy(candidate.legs).metrics()` reproduces the reported payoff metrics.
     */
    legs: Leg[];
}
Fields, parameters and returned members (16)

Loading 16 members…

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

type

ScanObjective

#

Ranking objective; expectedValuePerRisk (expected value ÷ max loss) is the default.

Signature
import type { ScanObjective } from '@insiderfinance/totalfinance/strategy/scanner';

/** Ranking objective; `expectedValuePerRisk` (expected value ÷ max loss) is the default. */
export type ScanObjective = (typeof SCAN_OBJECTIVES)[number];

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

iface

ScanOptions

#

Public declaration. Read the signature and member contracts below; no additional behaviour is inferred.

Signature
import type { ScanOptions } from '@insiderfinance/totalfinance/strategy/scanner';

export interface ScanOptions {
    /** Underlying spot price (WS3.2: renamed from `underlyingPrice` for workspace consistency). */
    spot: number;
    /**
     * Valuation instant. Epoch ms or a zoned ISO datetime, resolved at the boundary by core's
     * `resolveValuationAsOf` — the ONE valuation-instant grammar shared by `Position.probability()`,
     * the what-if cube and every other pricing boundary. A bare date is refused: a 0DTE's value
     * depends on the time of day.
     */
    asOf: EpochMs | string;
    /** Option expiry (`YYYY-MM-DD` → 16:00 ET, or a full datetime). */
    expiry: string;
    riskFreeRate: number;
    dividendYield?: number;
    /** The option chain — one row per strike, ascending or not (sorted internally). */
    chain: ScanQuoteRow[];
    /** Constant annualized volatility used for probabilityOfProfit / expectedValue scoring and to price any missing premiums. */
    volatility?: number;
    /**
     * Per-strike implied-volatility smile. Used to price any missing per-strike premiums (takes
     * precedence over `volatility`). **Scoring uses a SINGLE volatility:** `probabilityOfProfit` and
     * `expectedValue` are computed closed-form at the at-spot volatility `smile(spot)` (or
     * `volatility`), not the full smile — for smile-consistent probabilities, price a specific structure
     * with `Position.monteCarloProbability({ localVolatility })`.
     */
    smile?: (strike: number) => number;
    /** Which structures to enumerate (default: all). */
    structures?: ScanStructure[];
    /** Cap on the width (strike distance) of any single wing/spread, in price units. */
    maxWidth?: number;
    /** Keep only candidates with probability-of-profit ≥ this. */
    minProbabilityOfProfit?: number;
    /** Keep only candidates whose max loss ≤ this (in the position's P&L units — per contract, 100×). */
    maxRisk?: number;
    /** Ranking objective (default `expectedValuePerRisk`). */
    rankBy?: ScanObjective;
    /** Return only the top-N ranked candidates (default 25). */
    top?: number;
}
Fields, parameters and returned members (15)

Loading 15 members…

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

iface

ScanQuoteRow

#

One strike's market data. call/put are mid premiums; bid/ask feed the liquidity score.

Signature
import type { ScanQuoteRow } from '@insiderfinance/totalfinance/strategy/scanner';

/** One strike's market data. `call`/`put` are mid premiums; bid/ask feed the liquidity score. */
export interface ScanQuoteRow {
    strike: number;
    /** Call mid premium. If omitted, priced from `volatility`/`smile` via Black–Scholes. */
    call?: number;
    /** Put mid premium. If omitted, priced from `volatility`/`smile` via Black–Scholes. */
    put?: number;
    callBid?: number;
    callAsk?: number;
    putBid?: number;
    putAsk?: number;
}
Fields, parameters and returned members (7)
Name · typeMeaning · unitRequired · default
callnumber

Call mid premium. If omitted, priced from volatility/smile via Black–Scholes.

unitless by name
OptionalNo @default declared
callAsknumber—unitless by nameOptionalNo @default declared
callBidnumber—unitless by nameOptionalNo @default declared
putnumber

Put mid premium. If omitted, priced from volatility/smile via Black–Scholes.

unitless by name
OptionalNo @default declared
putAsknumber—unitless by nameOptionalNo @default declared
putBidnumber—unitless by nameOptionalNo @default declared
strikenumber—unitless by nameRequiredNo @default declared

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

iface

ScanResult

#

The scan report (Law 2 report grammar): the ranked candidates plus the applied conventions (assumptions) and a warnings channel (diagnostics).

Signature
import type { ScanResult } from '@insiderfinance/totalfinance/strategy/scanner';

/**
 * The scan report (Law 2 report grammar): the ranked candidates plus the applied conventions
 * (`assumptions`) and a warnings channel (`diagnostics`).
 */
export interface ScanResult {
    /** The top-N candidates by the ranking objective, descending, each fully metric'd. */
    candidates: ScanCandidate[];
    /** Applied conventions, echoed (Law 2 report grammar). */
    assumptions: {
        conventionsVersion: string;
        dayCount: 'ACT/365F';
        /** The ranking objective that produced the order (and each candidate's `score`). */
        rankBy: ScanObjective;
        /** The structures that were enumerated. */
        structures: ScanStructure[];
        /** Year fraction to the scanned expiry. */
        timeToExpiryYears: number;
        /** The single at-spot volatility that `probabilityOfProfit`/`expectedValue` are scored at (see the `smile` doc). */
        scoringVolatility: number;
    };
    /** Structured warnings; always present (possibly empty). */
    diagnostics: Diagnostics;
}
Fields, parameters and returned members (26)

Loading 26 members…

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

type

ScanStructure

#

The structures the scanner can enumerate (all single-expiry, defined-risk or long-premium).

Signature
import type { ScanStructure } from '@insiderfinance/totalfinance/strategy/scanner';

/** The structures the scanner can enumerate (all single-expiry, defined-risk or long-premium). */
export type ScanStructure = 'bullCallSpread' | 'bearCallSpread' | 'bullPutSpread' | 'bearPutSpread' | 'ironCondor' | 'ironButterfly' | 'longCallButterfly' | 'longPutButterfly' | 'straddle' | 'strangle';

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

fn

scanStrategies

#

Enumerate, score, and rank option structures over a strike grid. candidates carries the top-N by the chosen objective, each with the full payoff/probability metrics.

Signature
import { scanStrategies } from '@insiderfinance/totalfinance/strategy/scanner';

export declare function scanStrategies(options: ScanOptions): ScanResult;
Fields, parameters and returned members (24)

Loading 24 members…

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.