optopsy

A nimble backtesting and statistics library for options strategies.

Optopsy is a Python backtesting engine that lets you go from "How do 45-DTE iron condors on SPX perform with a 50% profit target and 2x stop loss vs holding to expiration?" to detailed performance statistics in seconds, not spreadsheets.

Full Documentation | API Reference | Examples

🤖 Looking for AI/LLM integration?

optopsy-mcp provides a high-performance MCP server for strategy screening and backtesting. Powered by a complete Rust rewrite of the Optopsy engine, it is specifically built for seamless interaction with Large Language Models.

Features

• 38 Built-in Strategies - From simple calls/puts to iron condors, butterflies, condors, ratio spreads, collars, calendars, and diagonals
• Per-Leg Delta Targeting - Select strikes by delta with target, min, max per leg
• Trade Simulator - Chronological simulation with capital tracking, position limits, and equity curves via simulate()
• Portfolio Simulation - Weighted multi-strategy portfolio backtesting via simulate_portfolio()
• Early Exits - Stop-loss, take-profit, and max-hold-days rules for automatic position management
• Commissions - Model broker fees with per-contract, base fee, and min fee structures
• Risk Metrics - Sharpe, Sortino, VaR, CVaR, Calmar, Omega, tail ratio, and more via compute_risk_metrics()
• 80+ Entry Signals - Filter entries with TA indicators (RSI, MACD, Bollinger Bands, EMA, ATR, IV Rank) via pandas-ta-classic
• Custom Signals - Use custom_signal() to drive entries from any DataFrame with a boolean flag column
• Slippage Modeling - Realistic fills with mid, spread, liquidity-based, or per-leg slippage
• Live Data Providers - Fetch options chains and stock prices directly from supported data sources (e.g. EODHD)
• Smart Caching - Automatic local caching of fetched data with gap detection for efficient re-fetches
• Plugin System - Extend with custom strategies, signals, and data providers via entry points

Installation

# Core library only (latest stable release)
pip install optopsy

# With Data CLI (download & cache market data)
pip install optopsy[data]

Requirements: Python 3.12-3.13, Pandas 2.0+, NumPy 1.26+

Data Management

Optopsy includes a standalone data CLI for downloading and caching historical market data.

pip install optopsy[data]

# Download historical options data (requires EODHD_API_KEY)
optopsy-data download SPY
optopsy-data download SPY AAPL TSLA

# Download stock price history
optopsy-data download SPY --stocks

# List available symbols
optopsy-data symbols
optopsy-data symbols -q SPY

# Cache management
optopsy-data cache size
optopsy-data cache clear

Data is cached locally as Parquet files at ~/.optopsy/cache/. Re-running download only fetches new data since your last download. See the Data Management documentation for full details.

Core Library Quick Start

import optopsy as op

# Load your options data
data = op.csv_data(
    "options_data.csv",
    underlying_symbol=0,
    option_type=2,
    expiration=3,
    quote_date=4,
    strike=5,
    bid=6,
    ask=7,
    delta=8,
)

# Backtest long calls and get performance statistics
results = op.long_calls(data)
print(results)

Output:

   dte_range   delta_range  count   mean    std    min    25%    50%    75%    max  win_rate  profit_factor
0    (0, 7]   (0.2, 0.3]    505   0.64   1.03  -1.00   0.14   0.37   0.87   7.62       ...            ...
1    (0, 7]   (0.3, 0.4]    269   2.34   8.65  -1.00  -1.00  -0.89   1.16  68.00       ...            ...
2   (7, 14]   (0.2, 0.3]    404   1.02   0.68  -0.46   0.58   0.86   1.32   4.40       ...            ...
...

Results are grouped by DTE (days to expiration) and delta range, showing descriptive statistics for percentage returns. Every run also returns win_rate (the fraction of trades with a positive return) and profit_factor (gross wins over gross losses); the values above depend on your dataset and are elided here.

Simulator

Run a full trade-by-trade simulation with capital tracking, position limits, and performance metrics:

result = op.simulate(
    data,
    op.long_calls,
    capital=100_000,
    quantity=1,
    max_positions=1,
    selector="nearest",       # "nearest", "highest_premium", "lowest_premium", or custom callable
    max_entry_dte=45,
    exit_dte=14,
)

print(result.summary)         # win rate, profit factor, max drawdown, etc.
print(result.trade_log)       # per-trade P&L, entry/exit dates, equity
print(result.equity_curve)    # portfolio value over time

The simulator works with all 38 strategies. It selects one trade per entry date, enforces concurrent position limits, and computes a full equity curve with metrics like win rate, profit factor, max drawdown, and average days in trade.

This is the beginning of the README. Read the rest at the original. Read the full README ↗