OptionsHelper

OptionsHelper is LumiBot’s high-level helper for options selection (expirations, strikes, deltas) and multi-leg order building/execution. For most options strategies, using OptionsHelper is both more reliable (avoids non-existent expiries/strikes during backtests) and much faster than brute-force approaches that scan large strike lists and call get_greeks() per strike.

Why use OptionsHelper?

Options backtests are easy to accidentally make slow or brittle. OptionsHelper exists to push strategies toward the safe, high-performance path:

  • Reliability in backtests: not every expiry/strike returned by a chain lookup is actually tradeable for the full backtest window. OptionsHelper methods validate that an option has usable market data.

  • Performance: brute-force patterns (scan many strikes and call get_greeks() or quote history per strike) can trigger a large number of data requests and slow backtests dramatically.

  • Cleaner strategy code: most common spreads can be built and executed with a few helper calls, without hand-assembling each leg.

If you are new to option data in LumiBot, also see:

Core conventions (important)

Rights and delta sign

OptionsHelper uses the standard conventions:

  • right is typically "call" or "put" (strings).

  • target_delta is positive for calls and negative for puts. Example: 20Δ call = +0.20; 20Δ put = -0.20.

Always pass underlying_price (float)

Many selection helpers require underlying_price. Always pass it explicitly as a float:

  • Prefer underlying_price=float(self.get_last_price(underlying_asset)) (after checking for None).

  • Call OptionsHelper.find_strike_for_delta(...) with keyword arguments. This prevents subtle argument-order mistakes.

Call get_chains once, then reuse it

self.get_chains(...) can be expensive depending on data source. When you need chains (for example, to pick an expiry), fetch them once per iteration and reuse the result.

Performance & reliability tips

Avoid brute-force delta hunting

Do not do this:

  • build a large strike list,

  • loop over strikes, and

  • call self.get_greeks() repeatedly to “hunt” a 20Δ strike.

That pattern is a common cause of slow runs because each greek/mark computation can trigger additional data work.

Instead, use:

  • OptionsHelper.find_strike_for_delta(...) (bounded probing + caching)

  • strategy-level caching: if you retry entry intraday, cache the selected expiry/strike(s) in self.vars and only recompute when the underlying moved materially.

Validate market data before trading

For live trading (and for realistic backtests), it is common to encounter:

  • missing bid/ask,

  • very wide spreads,

  • stale last trade prints.

Use OptionsHelper.evaluate_option_market(...) and gate trading on OptionsHelper.has_actionable_price(...).

Quickstart (delta-based strike)

from datetime import timedelta
from lumibot.entities import Asset
from lumibot.components.options_helper import OptionsHelper

def initialize(self):
    self.options_helper = OptionsHelper(self)

        def pick_20_delta_put(self):
            underlying = Asset("SPY", asset_type=Asset.AssetType.STOCK)
            chains = self.get_chains(underlying)
            if not chains:
        self.log_message("No option chains available", color="yellow")
        return None

    expiry = self.options_helper.get_expiration_on_or_after_date(
        self.get_datetime() + timedelta(days=0),
        chains,
        "put",
        underlying_asset=underlying,
    )
    if expiry is None:
        self.log_message("No valid expiry found", color="yellow")
        return None

    underlying_price = self.get_last_price(underlying)
    if underlying_price is None:
        self.log_message("Underlying price unavailable", color="yellow")
        return None

            strike = self.options_helper.find_strike_for_delta(
                underlying_asset=underlying,
                underlying_price=float(underlying_price),
                target_delta=-0.20,
                expiry=expiry,
                right="put",
            )
            return strike

Common workflows

1) Find a tradeable expiry near a target date

OptionsHelper.get_expiration_on_or_after_date(...) chooses an expiry on/after a target date and can validate that the expiry has tradeable data (when given underlying_asset).

from datetime import timedelta
from lumibot.entities import Asset

underlying = Asset("SPY", asset_type=Asset.AssetType.STOCK)
chains = self.get_chains(underlying)
if not chains:
    return

target_dt = self.get_datetime() + timedelta(days=7)
expiry = self.options_helper.get_expiration_on_or_after_date(
    target_dt,
    chains,
    "call",
    underlying_asset=underlying,
)

2) Pick a strike by delta (fast path)

Use OptionsHelper.find_strike_for_delta(...) instead of scanning strikes. Always pass keyword args.

underlying_price = self.get_last_price(underlying)
if underlying_price is None:
    return

put_strike = self.options_helper.find_strike_for_delta(
    underlying_asset=underlying,
    underlying_price=float(underlying_price),
    target_delta=-0.20,
    expiry=expiry,
    right="put",
)

3) Validate liquidity / data quality before placing orders

evaluate_option_market returns an OptionMarketEvaluation with prices and flags. Only trade when prices are actionable.

option = Asset(
    underlying.symbol,
    asset_type=Asset.AssetType.OPTION,
    expiration=expiry,
    strike=put_strike,
    right="put",
    underlying_asset=underlying,
)
evaluation = self.options_helper.evaluate_option_market(option, max_spread_pct=0.25)
self.log_message(f"Option evaluation: {evaluation}", color="blue")

if not self.options_helper.has_actionable_price(evaluation):
    self.log_message(f"Skipping trade: {evaluation.data_quality_flags}", color="yellow")
    return

4) Build multi-leg orders (spreads/condors) without hand-coding legs

Most common spreads have both:

  • a build_* helper that returns orders (so you can configure order type, risk logic, etc.), and

  • an execute_* helper that builds + submits for you.

Example: put credit spread (sell higher strike, buy lower strike).

orders = self.options_helper.build_put_vertical_spread_orders(
    underlying_asset=underlying,
    expiry=expiry,
    upper_strike=put_strike,           # short
    lower_strike=put_strike - 5.0,     # long wing
    quantity=1,
)
if not orders:
    return

limit_price = self.options_helper.calculate_multileg_limit_price(orders, limit_type="mid")
self.log_message(f"Mid price estimate: {limit_price}", color="blue")

# Submit however your strategy prefers (market/limit/smart limit, etc.)
self.submit_order(orders)

Examples (copy/paste patterns)

Sell a 20Δ put once per day (with caching)

This pattern avoids recomputing strike selection every iteration when nothing material changed.

def initialize(self):
    from lumibot.components.options_helper import OptionsHelper
    self.options_helper = OptionsHelper(self)
    self.vars.cached_put_strike = None
    self.vars.cached_put_expiry = None
    self.vars.cached_put_day = None
    self.vars.cached_spot = None

def _get_cached_20d_put_strike(self, underlying):
    from datetime import timedelta

    now = self.get_datetime()
    spot = self.get_last_price(underlying)
    if spot is None:
        return None, None

    today = now.date()
    if (
        self.vars.cached_put_day == today
        and self.vars.cached_put_strike is not None
        and self.vars.cached_put_expiry is not None
        and self.vars.cached_spot is not None
        and abs(float(spot) - float(self.vars.cached_spot)) / float(self.vars.cached_spot) < 0.005  # 0.5%
    ):
        return self.vars.cached_put_expiry, float(self.vars.cached_put_strike)

    chains = self.get_chains(underlying)
    if not chains:
        return None, None

    expiry = self.options_helper.get_expiration_on_or_after_date(
        now + timedelta(days=0),
        chains,
        "put",
        underlying_asset=underlying,
    )
    if expiry is None:
        return None, None

    strike = self.options_helper.find_strike_for_delta(
        underlying_asset=underlying,
        underlying_price=float(spot),
        target_delta=-0.20,
        expiry=expiry,
        right="put",
    )
    if strike is None:
        return None, None

    self.vars.cached_put_day = today
    self.vars.cached_put_expiry = expiry
    self.vars.cached_put_strike = float(strike)
    self.vars.cached_spot = float(spot)
    return expiry, float(strike)

Iron condor: pick short legs by delta, validate wings exist

For condors, a common pattern is:

  1. select short call + short put by delta,

  2. choose wing strikes at a fixed distance, and

  3. ensure wing strikes are real strikes for the chosen expiry (for example, by checking chains strikes).

If you are building a condor strategy, prefer:

  • find_strike_for_delta for the short legs, and

  • build_*_vertical_spread_orders to build each spread leg.

Troubleshooting

get_chains(...) returns None / empty

  • Not all assets have options, and data availability depends on your data source.

  • Always guard against None and log what asset/when you queried.

get_greeks(...) returns None

This often means the option does not have usable price/quote inputs at that time (illiquid, missing quote history, etc.).

  • Always handle None and continue strategy execution.

  • Prefer evaluate_option_market to understand what price inputs are missing and why.

find_strike_for_delta(...) returns None

Common causes:

  • no valid expiry was found (start by validating expiry selection),

  • the chain does not include the expected strike neighborhood,

  • missing option marks for candidate strikes (data gap / illiquid contracts).

In these cases, log and skip for the iteration/day rather than crashing.

API Reference

class lumibot.components.options_helper.OptionMarketEvaluation(bid: float | None, ask: float | None, last_price: float | None, spread_pct: float | None, has_bid_ask: bool, spread_too_wide: bool, missing_bid_ask: bool, missing_last_price: bool, buy_price: float | None, sell_price: float | None, used_last_price_fallback: bool, max_spread_pct: float | None, data_quality_flags: List[str])

Structured result from evaluate_option_market.

class lumibot.components.options_helper.OptionsHelper(strategy)

OptionsHelper is a utility component for constructing and managing various options strategies. It provides functions for:

  • Finding valid options (e.g. handling expiries on holidays/weekends)

  • Calculating option deltas and finding strikes that best match target deltas

  • Calculating a multi-leg limit price for orders

  • Building orders for various spread strategies (vertical, calendar, butterfly, straddle, strangle, diagonal, ratio)

  • Executing (submitting) the constructed orders separately from building them

  • Advanced risk management functions such as aggregating portfolio Greeks and checking spread profit

  • Additional utility functions for liquidity checking and order detail summaries

static has_actionable_price(evaluation: OptionMarketEvaluation | None) → bool

Return True when the evaluation contains usable buy and sell prices.

A quote can be “one-sided” (ask-only or bid-only). In that case we cannot safely execute both buy and sell actions, so treat it as non-actionable.

find_next_valid_option(underlying_asset: Asset, rounded_underlying_price: float, expiry: date, put_or_call: str = 'call') → Asset | None

Find a valid option with the given expiry and strike. First tries the requested strike, then searches nearby strikes from the option chain. If no strikes work for this expiry, tries the next expiry date.

Parameters:

  • underlying_asset (Asset) – The underlying asset.

  • rounded_underlying_price (float) – The intended strike (usually the underlying price rounded to a strike step).

  • expiry (date) – The target expiry date.

  • put_or_call (str, optional) – “call” or “put” (default is “call”).

Returns:

The valid option asset or None if not found.

Return type:

Optional[Asset]

get_strike_deltas(underlying_asset: Asset, expiry: date, strikes: List[float], right: str, stop_greater_than: float | None = None, stop_less_than: float | None = None) → Dict[float, float | None]

Compute the delta for each strike in a given list.

Parameters:

  • underlying_asset (Asset) – The underlying asset.

  • expiry (date) – The expiry date.

  • strikes (List[float]) – List of strike prices.

  • right (str) – “call” or “put”.

  • stop_greater_than (Optional[float]) – Stop iteration if a computed delta is >= this value.

  • stop_less_than (Optional[float]) – Stop iteration if a computed delta is <= this value.

Returns:

Mapping from strike price to its delta.

Return type:

Dict[float, Optional[float]]

get_delta_for_strike(underlying_asset: Asset, underlying_price: float, strike: float, expiry: date, right: str) → float | None

Retrieve the delta for an option with a specific strike.

Parameters:

  • underlying_asset (Asset) – The underlying asset.

  • underlying_price (float) – Current underlying price.

  • strike (float) – The strike price.

  • expiry (date) – The option’s expiry date.

  • right (str) – “call” or “put”.

Returns:

The computed delta or None if unavailable.

Return type:

Optional[float]

find_strike_for_delta(underlying_asset: Asset, underlying_price: float, target_delta: float, expiry: date, right: str) → float | None

Find the strike whose delta is closest to the target delta using binary search. (This function replaces the older “find_strike_for_delta_original”.)

Parameters:

  • underlying_asset (Asset) – The underlying asset.

  • underlying_price (float) – Current (rounded) price of the underlying.

  • target_delta (float) – Desired target delta (positive for calls, negative for puts).

  • expiry (date) – The option expiry date.

  • right (str) – “call” or “put”.

Returns:

The strike price that best matches the target delta, or None.

Return type:

Optional[float]

calculate_multileg_limit_price(orders: List[Order], limit_type: str) → float | None

Calculate an aggregate limit price for a multi-leg order by combining quotes from each leg.

Parameters:

  • orders (List[Order]) – List of orders (each order has an Asset).

  • limit_type (str) – One of “best”, “fastest”, or “mid” indicating which price to use.

Returns:

The aggregated limit price, or None if quotes are missing.

Return type:

Optional[float]

evaluate_option_market(option_asset: Asset, max_spread_pct: float | None = None) → OptionMarketEvaluation

Evaluate available quote data for an option and produce execution anchors.

Parameters:

  • option_asset (Asset) – The option to evaluate.

  • max_spread_pct (float, optional) – Maximum acceptable bid/ask spread as a fraction (e.g. 0.25 for 25%).

Returns:

Dataclass containing quote fields, derived spread information, and suggested buy/sell prices (with automatic fallback when the data source allows it).

Return type:

OptionMarketEvaluation

check_option_liquidity(option_asset: Asset, max_spread_pct: float) → bool

Check if an option’s bid-ask spread is within an acceptable threshold.

Parameters:

  • option_asset (Asset) – The option asset to check.

  • max_spread_pct (float) – Maximum allowed spread as a fraction (e.g. 0.15 for 15%).

Returns:

True if the option is sufficiently liquid; False otherwise.

Return type:

bool

get_order_details(order: Order) → Dict[str, str | float | date | None]

Return a summary of key details of an order for logging and debugging.

Parameters:

order (Order) – The order to summarize.

Returns:

A dictionary containing symbol, strike, expiration, right, side, and last price.

Return type:

Dict[str, Optional[Union[str, float, date]]]

get_expiration_on_or_after_date(dt: date | datetime, chains: Dict[str, Any] | Chains, call_or_put: str, underlying_asset: Asset | None = None, allow_prior: bool = False) → date | None

Get the expiration date that is on or after a given date, validating that the option has tradeable data.

Parameters:

  • dt (date) – The starting date. Can be a datetime.date or datetime.datetime object.

  • chains (dict or Chains) – A dictionary or Chains object containing option chains.

  • call_or_put (str) – One of “call” or “put”.

  • underlying_asset (Asset, optional) – The underlying asset to validate option data. If provided, will verify option has tradeable data.

  • allow_prior (bool, optional) – When True, if no valid expiration exists on/after dt (often because far-dated expirations were not listed yet at the backtest date), fall back to the latest valid expiration before dt.

Returns:

The adjusted expiration date with valid tradeable data.

Return type:

date

build_call_orders(underlying_asset: Asset, expiry: date, call_strike: float, quantity_to_trade: int, wing_size: float) → Tuple[Order | None, Order | None]

Build call orders for a spread without submitting them. This builds a sell order at the given call_strike and a buy order at (call_strike + wing_size).

Parameters:

  • underlying_asset (Asset) – The underlying asset.

  • expiry (date) – Option expiry date.

  • call_strike (float) – Selected call strike for the short leg.

  • quantity_to_trade (int) – Number of contracts.

  • wing_size (float) – Offset for the long leg (buy leg).

Returns:

(call_sell_order, call_buy_order) or (None, None) if prices are unavailable.

Return type:

Tuple[Optional[Order], Optional[Order]]

build_put_orders(underlying_asset: Asset, expiry: date, put_strike: float, quantity_to_trade: int, wing_size: float) → Tuple[Order | None, Order | None]

Build put orders for a spread without submitting them. This builds a sell order at the given put_strike and a buy order at (put_strike - wing_size).

Parameters:

  • underlying_asset (Asset) – The underlying asset.

  • expiry (date) – Option expiry date.

  • put_strike (float) – Selected put strike for the short leg.

  • quantity_to_trade (int) – Number of contracts.

  • wing_size (float) – Offset for the long leg (buy leg).

Returns:

(put_sell_order, put_buy_order) or (None, None) if prices are unavailable.

Return type:

Tuple[Optional[Order], Optional[Order]]

build_call_vertical_spread_orders(underlying_asset: Asset, expiry: date, lower_strike: float, upper_strike: float, quantity: int) → List[Order]

Build orders for a call vertical spread (bull call spread) without submitting them. The spread consists of buying a call at lower_strike and selling a call at upper_strike.

Parameters:

  • underlying_asset (Asset) – The underlying asset.

  • expiry (date) – Option expiry.

  • lower_strike (float) – Strike for the long call.

  • upper_strike (float) – Strike for the short call.

  • quantity (int) – Number of contracts.

Returns:

A list containing the buy order (long call) and the sell order (short call).

Return type:

List[Order]

build_put_vertical_spread_orders(underlying_asset: Asset, expiry: date, upper_strike: float, lower_strike: float, quantity: int) → List[Order]

Build orders for a put vertical spread (bull put spread) without submitting them. The spread consists of selling a put at upper_strike and buying a put at lower_strike.

Parameters:

  • underlying_asset (Asset) – The underlying asset.

  • expiry (date) – Option expiry.

  • upper_strike (float) – Strike for the short put.

  • lower_strike (float) – Strike for the long put.

  • quantity (int) – Number of contracts.

Returns:

A list containing the sell order (short put) and the buy order (long put).

Return type:

List[Order]

build_calendar_spread_orders(underlying_asset: Asset, strike: float, near_expiry: date, far_expiry: date, quantity: int, right: str) → List[Order]

Build orders for a calendar spread (same strike, different expiries) without submitting them. Typically, the near expiry option is sold and the far expiry option is bought.

Parameters:

  • underlying_asset (Asset) – The underlying asset.

  • strike (float) – Strike price for both legs.

  • near_expiry (date) – Near expiry date (sell leg).

  • far_expiry (date) – Far expiry date (buy leg).

  • quantity (int) – Number of contracts.

  • right (str) – Option type (“call” or “put”).

Returns:

A list containing the sell order and the buy order.

Return type:

List[Order]

build_butterfly_spread_orders(underlying_asset: Asset, expiry: date, lower_strike: float, middle_strike: float, upper_strike: float, quantity: int, right: str) → List[Order]

Build orders for a butterfly spread without submitting them. For a call butterfly: buy 1 call at lower_strike, sell 2 calls at middle_strike, and buy 1 call at upper_strike. For a put butterfly, similar logic applies.

Parameters:

  • underlying_asset (Asset) – The underlying asset.

  • expiry (date) – Option expiry.

  • lower_strike (float) – Lower strike (long leg).

  • middle_strike (float) – Middle strike (short leg, double quantity).

  • upper_strike (float) – Upper strike (long leg).

  • quantity (int) – Number of butterfly spreads (each spread uses a 1-2-1 ratio).

  • right (str) – Option type (“call” or “put”).

Returns:

A list of orders representing the butterfly spread.

Return type:

List[Order]

build_straddle_orders(underlying_asset: Asset, expiry: date, strike: float, quantity: int) → List[Order]

Build orders for a straddle without submitting them by buying both a call and a put at the same strike.

Parameters:

  • underlying_asset (Asset) – The underlying asset.

  • expiry (date) – Option expiry.

  • strike (float) – The strike price.

  • quantity (int) – Number of contracts.

Returns:

A list containing the call order and the put order.

Return type:

List[Order]

build_strangle_orders(underlying_asset: Asset, expiry: date, lower_strike: float, upper_strike: float, quantity: int) → List[Order]

Build orders for a strangle without submitting them by buying a put at a lower strike and a call at a higher strike.

Parameters:

  • underlying_asset (Asset) – The underlying asset.

  • expiry (date) – Option expiry.

  • lower_strike (float) – Strike for the put.

  • upper_strike (float) – Strike for the call.

  • quantity (int) – Number of contracts.

Returns:

A list containing the put order and the call order.

Return type:

List[Order]

build_diagonal_spread_orders(underlying_asset: Asset, near_expiry: date, far_expiry: date, near_strike: float, far_strike: float, quantity: int, right: str) → List[Order]

Build orders for a diagonal spread without submitting them. For example, for a call diagonal spread, sell a near-expiry call at near_strike and buy a far-expiry call at far_strike.

Parameters:

  • underlying_asset (Asset) – The underlying asset.

  • near_expiry (date) – The near expiry date (sell leg).

  • far_expiry (date) – The far expiry date (buy leg).

  • near_strike (float) – Strike for the near-expiry (sell) option.

  • far_strike (float) – Strike for the far-expiry (buy) option.

  • quantity (int) – Number of contracts.

  • right (str) – Option type (“call” or “put”).

Returns:

A list containing the sell order and the buy order.

Return type:

List[Order]

build_ratio_spread_orders(underlying_asset: Asset, expiry: date, buy_strike: float, sell_strike: float, buy_qty: int, sell_qty: int, right: str) → List[Order]

Build orders for a ratio spread without submitting them. For example, buy one option at buy_strike and sell a different number at sell_strike.

Parameters:

  • underlying_asset (Asset) – The underlying asset.

  • expiry (date) – Option expiry.

  • buy_strike (float) – Strike for the long leg.

  • sell_strike (float) – Strike for the short leg.

  • buy_qty (int) – Quantity for the long leg.

  • sell_qty (int) – Quantity for the short leg.

  • right (str) – Option type (“call” or “put”).

Returns:

A list containing the long order and the short order.

Return type:

List[Order]

execute_orders(orders: List[Order], limit_type: str | None = None) → bool

Submit a list of orders as a multi-leg order. If a limit_type is provided, calculate a limit price and submit with that price.

Parameters:

  • orders (List[Order]) – A list of orders to submit.

  • limit_type (Optional[str]) – One of “best”, “fastest”, or “mid” for limit pricing.

Returns:

True if orders are submitted successfully.

Return type:

bool

execute_call_vertical_spread(underlying_asset: Asset, expiry: date, lower_strike: float, upper_strike: float, quantity: int, limit_type: str | None = None) → bool

Build and submit orders for a call vertical spread.

Parameters:

  • underlying_asset (Asset) – The underlying asset.

  • expiry (date) – Option expiry.

  • lower_strike (float) – Strike for the long call.

  • upper_strike (float) – Strike for the short call.

  • quantity (int) – Number of contracts.

  • limit_type (Optional[str]) – Limit pricing type.

Returns:

True if orders are submitted successfully.

Return type:

bool

execute_put_vertical_spread(underlying_asset: Asset, expiry: date, upper_strike: float, lower_strike: float, quantity: int, limit_type: str | None = None) → bool

Build and submit orders for a put vertical spread.

Parameters:

  • underlying_asset (Asset) – The underlying asset.

  • expiry (date) – Option expiry.

  • upper_strike (float) – Strike for the short put.

  • lower_strike (float) – Strike for the long put.

  • quantity (int) – Number of contracts.

  • limit_type (Optional[str]) – Limit pricing type.

Returns:

True if orders are submitted successfully.

Return type:

bool

execute_calendar_spread(underlying_asset: Asset, strike: float, near_expiry: date, far_expiry: date, quantity: int, right: str, limit_type: str | None = None) → bool

Build and submit orders for a calendar spread.

Parameters:

  • underlying_asset (Asset) – The underlying asset.

  • strike (float) – Strike price for both legs.

  • near_expiry (date) – Near expiry date (sell leg).

  • far_expiry (date) – Far expiry date (buy leg).

  • quantity (int) – Number of contracts.

  • right (str) – Option type (“call” or “put”).

  • limit_type (Optional[str]) – Limit pricing type.

Returns:

True if orders are submitted successfully.

Return type:

bool

execute_butterfly_spread(underlying_asset: Asset, expiry: date, lower_strike: float, middle_strike: float, upper_strike: float, quantity: int, right: str, limit_type: str | None = None) → bool

Build and submit orders for a butterfly spread.

Parameters:

  • underlying_asset (Asset) – The underlying asset.

  • expiry (date) – Option expiry.

  • lower_strike (float) – Lower strike for long leg.

  • middle_strike (float) – Middle strike for the short leg.

  • upper_strike (float) – Upper strike for long leg.

  • quantity (int) – Number of butterfly spreads (1-2-1 ratio).

  • right (str) – Option type (“call” or “put”).

  • limit_type (Optional[str]) – Limit pricing type.

Returns:

True if orders are submitted successfully.

Return type:

bool

execute_straddle(underlying_asset: Asset, expiry: date, strike: float, quantity: int, limit_type: str | None = None) → bool

Build and submit orders for a straddle.

Parameters:

  • underlying_asset (Asset) – The underlying asset.

  • expiry (date) – Option expiry.

  • strike (float) – The strike price.

  • quantity (int) – Number of contracts.

  • limit_type (Optional[str]) – Limit pricing type.

Returns:

True if orders are submitted successfully.

Return type:

bool

execute_strangle(underlying_asset: Asset, expiry: date, lower_strike: float, upper_strike: float, quantity: int, limit_type: str | None = None) → bool

Build and submit orders for a strangle.

Parameters:

  • underlying_asset (Asset) – The underlying asset.

  • expiry (date) – Option expiry.

  • lower_strike (float) – Strike for the put.

  • upper_strike (float) – Strike for the call.

  • quantity (int) – Number of contracts.

  • limit_type (Optional[str]) – Limit pricing type.

Returns:

True if orders are submitted successfully.

Return type:

bool

execute_diagonal_spread(underlying_asset: Asset, near_expiry: date, far_expiry: date, near_strike: float, far_strike: float, quantity: int, right: str, limit_type: str | None = None) → bool

Build and submit orders for a diagonal spread.

Parameters:

  • underlying_asset (Asset) – The underlying asset.

  • near_expiry (date) – Near expiry date (sell leg).

  • far_expiry (date) – Far expiry date (buy leg).

  • near_strike (float) – Strike for the near-expiry (sell) option.

  • far_strike (float) – Strike for the far-expiry (buy) option.

  • quantity (int) – Number of contracts.

  • right (str) – Option type (“call” or “put”).

  • limit_type (Optional[str]) – Limit pricing type.

Returns:

True if orders are submitted successfully.

Return type:

bool

execute_ratio_spread(underlying_asset: Asset, expiry: date, buy_strike: float, sell_strike: float, buy_qty: int, sell_qty: int, right: str, limit_type: str | None = None) → bool

Build and submit orders for a ratio spread.

Parameters:

  • underlying_asset (Asset) – The underlying asset.

  • expiry (date) – Option expiry.

  • buy_strike (float) – Strike for the long leg.

  • sell_strike (float) – Strike for the short leg.

  • buy_qty (int) – Quantity for the long leg.

  • sell_qty (int) – Quantity for the short leg.

  • right (str) – Option type (“call” or “put”).

  • limit_type (Optional[str]) – Limit pricing type.

Returns:

True if orders are submitted successfully.

Return type:

bool

aggregate_portfolio_greeks(positions: List, underlying_asset: Asset) → Dict[str, float]

Aggregate the Greeks (delta, gamma, theta, and vega) for a list of option positions. Useful for obtaining an overall risk profile of the options portfolio.

Parameters:

  • positions (List) – A list of position objects. Each position should have an ‘asset’ and a ‘quantity’.

  • underlying_asset (Asset) – The underlying asset.

Returns:

A dictionary with aggregated values for “delta”, “gamma”, “theta”, and “vega”.

Return type:

Dict[str, float]

check_spread_profit(initial_cost: float, orders: List[Order], contract_multiplier: int = 100) → float | None

Calculate the current profit or loss percentage of a spread based on updated market prices.

Parameters:

  • initial_cost (float) – The initial net cost (or credit) of establishing the spread.

  • orders (List[Order]) – The list of orders that constitute the spread.

  • contract_multiplier (int, optional) – The Option contract multiplier to use (default is 100)

Returns:

The profit/loss percentage relative to the initial cost, or None if any leg’s price is unavailable.

Return type:

Optional[float]