options-strategy

Purpose

Backtesting of option portfolio strategies. Starting from the underlying price, the engine synthesizes theoretical option prices with the Black-Scholes model, then simulates PnL, Greeks exposure, and expiration exercise for multi-leg option portfolios.

Applicable scenarios:

• Hedging strategies (covered call, protective put)
• Volatility trading (straddle, strangle)
• Spread strategies (iron condor, butterfly, calendar spread)
• Option pricing analysis and Greeks sensitivity research

Supported Strategy Types

OptionsSignalEngine Interface

Write the strategy in code/signal_engine.py, with class name SignalEngine, implementing the generate method:

class SignalEngine:
    """Option strategy signal engine."""

    def generate(self, data_map: dict) -> list:
        """Generate option trading instructions.

        Args:
            data_map: code -> DataFrame (columns: open, high, low, close, volume)

        Returns:
            List of trading instructions. Each instruction has the format:
            {
                "date": "2024-01-15",        # Trading date
                "action": "open" / "close",  # Open or close position
                "underlying": "BTC-USDT",    # Underlying code
                "legs": [                    # List of option legs
                    {
                        "type": "call" / "put",  # Option type
                        "strike": 50000,          # Strike price
                        "expiry": "2024-02-15",   # Expiration date
                        "qty": 1                  # Quantity (positive = long, negative = short)
                    }
                ]
            }
        """

Multi-Leg Combination Example

Iron Condor opening signal:

{
    "date": "2024-01-15",
    "action": "open",
    "underlying": "000300.SH",
    "legs": [
        {"type": "put",  "strike": 3800, "expiry": "2024-02-15", "qty": -1},  # Sell put
        {"type": "put",  "strike": 3700, "expiry": "2024-02-15", "qty":  1},  # Buy protective put
        {"type": "call", "strike": 4200, "expiry": "2024-02-15", "qty": -1},  # Sell call
        {"type": "call", "strike": 4300, "expiry": "2024-02-15", "qty":  1},  # Buy protective call
    ]
}

config.json Format

{
    "codes": ["000300.SH"],
    "start_date": "2020-01-01",
    "end_date": "2024-12-31",
    "source": "tushare",
    "engine": "options",
    "initial_cash": 1000000,
    "commission": 0.001,
    "options_config": {
        "risk_free_rate": 0.05,
        "iv_source": "historical",
        "contract_multiplier": 1.0,
        "same_day_fill": false,
        "default_iv": 0.3
    }
}

Key fields:

• engine must be set to "options" so the runner selects the option backtest engine
• options_config.risk_free_rate: risk-free rate, default 0.05
• options_config.iv_source: volatility source, currently supports "historical" (30-day rolling historical volatility computed from underlying closes)
• options_config.contract_multiplier: contract multiplier, default 1.0
• options_config.same_day_fill: false (default) fills a signal dated T on the next bar's close; true restores the legacy same-date fill (signal and fill share T's close and IV)
• options_config.default_iv: volatility used for bars without a full rolling window (warm-up and NaN gaps), default 0.3; must be finite and positive

BS Model Principles

Black-Scholes formula (European options):

Call = S * N(d1) - K * e^(-rT) * N(d2)
Put  = K * e^(-rT) * N(-d2) - S * N(-d1)

d1 = [ln(S/K) + (r + sigma^2/2) * T] / (sigma * sqrt(T))
d2 = d1 - sigma * sqrt(T)

Where S = underlying price, K = strike, T = time to expiry in years, r = risk-free rate, sigma = volatility, and N() = cumulative distribution function of the standard normal.

This engine starts from the underlying daily price series, substitutes historical volatility for implied volatility, and computes theoretical option prices through the BS formula. This is a synthetic-data mode, meaning no real option market data is required.

Greeks Meaning and Usage

The backtest engine computes portfolio-level Greeks aggregates on each trading day and outputs them to greeks.csv.

Common Pitfalls

Volatility Smile

The BS model assumes constant volatility, but in real markets implied volatility differs across strikes and expiries (volatility smile / skew). This engine approximates with historical volatility, so pricing may be biased for deep OTM / deep ITM options. Strategy design should avoid over-reliance on pricing precision at extreme strikes.

Time Decay (Theta Decay)

Theta decay is not linear — the closer the option is to expiry, the faster the decay. The last 30 days decay much faster than the prior 30 days. Short-vol strategies benefit from this, but Gamma risk also rises sharply near expiry.

Early Exercise

This engine supports European options only (exercise only at expiry), not American options. In scenarios with meaningful early-exercise value (for example, deep ITM puts or calls on high-dividend underlyings), pricing will be biased.

Liquidity and Slippage

In synthetic-data mode there are no bid-ask spreads or liquidity constraints. In real trading, deep OTM options have poor liquidity and wide spreads, so backtest results will be overly optimistic.

Contract Multiplier

Option contract multipliers differ across markets (for example, China A-share ETF options often use a 10,000 multiplier, while crypto is typically 1). Make sure options_config.contract_multiplier is set correctly.

Artifact Description

After backtesting, the following files are generated in the artifacts/ directory:

Pricing Tool

The Agent can call the options_pricing tool for one-off pricing:

Call the options_pricing tool with:
  spot: 50000
  strike: 52000
  expiry_days: 30
  volatility: 0.6
  option_type: "call"

It returns the theoretical price and Greeks, which is suitable for interactive analysis.