options-spread-conviction-engineMulti-regime options spread analysis engine with Kelly Criterion Position Sizing. Scores vertical spreads (bull put, bear call, bull call, bear put) and mult...
Install via ClawdBot CLI:
clawdbot install AdamNaghs/options-spread-conviction-engineMulti-regime options spread scoring using technical indicators and IV term structure analysis.
brew install jq
npm install yahoo-finance2
sudo ln -s /opt/homebrew/bin/yahoo-finance /usr/local/bin/yfThis engine analyzes any ticker and scores seven options strategies across two categories:
| Strategy | Type | Philosophy | Ideal Setup |
|----------|------|------------|-------------|
| bull_put | Credit | Mean Reversion | Bullish trend + oversold dip |
| bear_call | Credit | Mean Reversion | Bearish trend + overbought rip |
| bull_call | Debit | Breakout | Strong bullish momentum |
| bear_put | Debit | Breakout | Strong bearish momentum |
| Strategy | Type | Philosophy | Ideal Setup |
|----------|------|------------|-------------|
| iron_condor | Credit | Premium Selling | IV Rank >70, RSI neutral, range-bound |
| butterfly | Debit | Pinning Play | BB squeeze, RSI center, low ADX |
| calendar | Debit | Theta Harvest | Inverted IV term structure (front > back) |
Weights vary by strategy type (Credit = Mean Reversion, Debit = Breakout):
| Indicator | Weight | Purpose |
|-----------|--------|---------|
| Ichimoku Cloud | 25 pts | Trend structure & equilibrium |
| RSI | 20 pts | Entry timing (mean-reversion) |
| MACD | 15 pts | Momentum confirmation |
| Bollinger Bands | 25 pts | Volatility regime |
| ADX | 15 pts | Trend strength validation |
| Indicator | Weight | Purpose |
|-----------|--------|---------|
| Ichimoku Cloud | 20 pts | Trend confirmation |
| RSI | 10 pts | Directional momentum |
| MACD | 30 pts | Breakout acceleration |
| Bollinger Bands | 25 pts | Bandwidth expansion |
| ADX | 15 pts | Trend strength validation |
| Component | Weight | Rationale |
|-----------|--------|-----------|
| IV Rank (BBW %) | 25 pts | Rich premiums to sell |
| RSI Neutrality | 20 pts | No directional momentum |
| ADX Range-Bound | 20 pts | Weak trend = range structure |
| Price Position | 20 pts | Centered in range = safe margins |
| MACD Neutrality | 15 pts | No acceleration in any direction |
Triggers:
Strike Selection:
Output:
| Component | Weight | Rationale |
|-----------|--------|-----------|
| BB Squeeze | 30 pts | Vol compression = narrow range |
| RSI Neutrality | 25 pts | Price at equilibrium |
| ADX Weakness | 20 pts | No directional trend at all |
| Price Centering | 15 pts | At center of range for max profit |
| MACD Flatness | 10 pts | No momentum |
Triggers:
Strike Selection:
Output:
| Component | Weight | Rationale |
|-----------|--------|-----------|
| IV Term Structure | 30 pts | Front IV > Back IV = theta edge |
| Price Stability | 20 pts | Price stays near strike |
| RSI Neutrality | 20 pts | Not trending away from strike |
| ADX Moderate | 15 pts | Some structure, not trending hard |
| MACD Neutrality | 15 pts | No directional acceleration |
Triggers:
Data Sources:
Strike Selection:
Output:
| Score | Tier | Action |
|-------|------|--------|
| 80-100 | EXECUTE | High conviction ā Enter the spread |
| 60-79 | PREPARE | Favorable ā Size the trade |
| 40-59 | WATCH | Interesting ā Add to watchlist |
| 0-39 | WAIT | Poor conditions ā Avoid / No setup |
# Basic analysis (auto-detects best strategy)
conviction-engine AAPL
# Specific strategy
conviction-engine SPY --strategy bear_call
conviction-engine QQQ --strategy bull_call --period 2y# Iron Condor ā high IV, range-bound
conviction-engine SPY --strategy iron_condor
# Butterfly ā volatility compression, pinning play
conviction-engine AAPL --strategy butterfly
# Calendar ā inverted IV term structure, theta harvest
conviction-engine TSLA --strategy calendarconviction-engine AAPL MSFT GOOGL --strategy bull_put
conviction-engine SPY QQQ IWM --strategy iron_condorconviction-engine TSLA --strategy butterfly --json
conviction-engine SPY --strategy calendar --json | jq '.[0].iv_term_structure'conviction-engine <ticker> [ticker...]
--strategy {bull_put,bear_call,bull_call,bear_put,iron_condor,butterfly,calendar}
--period {1y,2y,3y,5y}
--interval {1h,1d,1wk}
--json================================================================================
SPY ā Iron Condor (Credit)
================================================================================
Price: $681.27 | Score: 31.8/100 ā WAIT
[IV Rank +2.5/25]
IV Rank (BBW proxy): 5% (VERY_LOW)
BBW: 3.17 (1Y range: 2.37 - 18.13)
Premiums are THIN ā poor risk/reward for credit
Strikes:
BUY 680.0P | SELL 685.0P
SELL 695.0C | BUY 700.0C
Max Profit Zone: $685.0 - $695.0
Wing Width: $5.00================================================================================
SPY ā Long Butterfly (Debit)
================================================================================
Price: $681.27 | Score: 64.5/100 ā PREPARE
[BB Squeeze +27.0/30]
Bandwidth: 3.1701 (percentile: 21%)
SQUEEZE ACTIVE ā 19 consecutive bars
Strikes:
BUY 1x 685.0C | SELL 2x 690.0C | BUY 1x 695.0C
Max Profit Price: $690.0
Profit Zone: ~$685.0 - $695.0================================================================================
SPY ā Calendar Spread (Debit)
================================================================================
Price: $681.27 | Score: 67.2/100 ā PREPARE
[IV Term Structure +30.0/30]
Front IV: 27.5% | Back IV: 19.4%
Differential: +41.7%
INVERTED TERM STRUCTURE ā calendar opportunity confirmed
Strikes:
Strike: $680.0
SELL 2026-02-13 | BUY 2026-03-13
Theta Advantage: Front IV > Back IV by 41.7%IV Rank is approximated using Bollinger Bandwidth (BBW) percentile over 252 trading days:
IV Rank ā (Current BBW - 52wk Low BBW) / (52wk High BBW - 52wk Low BBW) Ć 100This correlation is well-documented: realized volatility (BBW) and implied volatility rank move with ~0.7-0.8 correlation (Sinclair, "Volatility Trading", 2013).
For calendar spreads, the engine attempts to fetch live ATM implied volatility from Yahoo Finance options chains. If unavailable, it falls back to historical volatility term structure (HV 10-day vs HV 30-day) as a proxy.
The engine now includes four quantitative modules for rigorous strategy validation and optimization:
regime_detector.py)Market regime classification using VIX percentiles:
# Detect current regime
python3 scripts/regime_detector.py
# Get regime-adjusted weights for specific strategy
python3 scripts/regime_detector.py --strategy iron_condor --jsonIntegration:
from regime_detector import RegimeDetector
detector = RegimeDetector()
regime, confidence = detector.detect_regime()
weights = detector.get_regime_weights(regime)
adjusted_score, reasoning = detector.regime_aware_score(75, regime, 'bull_put')vol_forecaster.py)GARCH-based realized volatility forecasting with VRP analysis:
# Analyze AAPL volatility
python3 scripts/vol_forecaster.py AAPL
# Compare IV = 25% vs forecast RV
python3 scripts/vol_forecaster.py SPY --iv 0.25 --horizon 5Interpretation:
Integration:
from vol_forecaster import VolatilityForecaster
forecaster = VolatilityForecaster("AAPL")
params = forecaster.fit_garch() # Returns omega, alpha, beta
forecast = forecaster.forecast_vol(horizon=5)
vrp, strength, rec = forecaster.vol_risk_premium(iv=0.25, rv_forecast=forecast.annualized_vol)
adjusted_score, reasoning = forecaster.add_to_conviction(70, vrp_signal, 'bull_put')enhanced_kelly.py)Drawdown-constrained, correlation-aware position sizing:
# Calculate position with $390 account
python3 scripts/enhanced_kelly.py --loss 80 --win 40 --pop 0.65 --conviction 85
# Include correlation with existing position
python3 scripts/enhanced_kelly.py --loss 80 --win 40 --pop 0.65 --conviction 85 --correlation 0.3Integration:
from enhanced_kelly import EnhancedKellySizer
sizer = EnhancedKellySizer(account_value=390, max_drawdown=0.20)
result = sizer.calculate_position(
spread_cost=80,
max_loss=80,
win_amount=40,
conviction=85,
pop=0.65,
existing_correlation=0.0
)
# Returns: contracts, total_risk, kelly_fraction, recommendationbacktest_validator.py)Walk-forward validation of conviction scores:
# Backtest bull_put on AAPL, MSFT, SPY (2022-2024)
python3 scripts/backtest_validator.py --tickers AAPL MSFT SPY --start 2022-01-01 --end 2024-01-01 --strategy bull_put
# JSON output for analysis
python3 scripts/backtest_validator.py --tickers SPY --jsonOutput Metrics:
Integration:
from backtest_validator import BacktestValidator
validator = BacktestValidator(engine, "2022-01-01", "2024-01-01")
results_df = validator.run_walk_forward(["AAPL", "MSFT"], hold_days=5)
report = validator.validate_tiers(results_df)
print(f"Separation score: {report.tier_separation_score:.2f}")
print(f"EXECUTE vs WAIT p-value: {report.p_values['execute_vs_wait']:.4f}")quantitative_integration.py)Unified interface combining all quantitative modules:
# Full quantitative analysis with regime and VRP
python3 scripts/quantitative_integration.py AAPL --regime-aware --vol-aware
# With Kelly sizing
python3 scripts/quantitative_integration.py SPY --regime-aware --pop 0.65 --max-loss 80 --win-amount 40
# Run backtest validation
python3 scripts/quantitative_integration.py --backtest SPY QQQ --start 2022-01-01 --end 2024-01-01Integration:
from quantitative_integration import QuantConvictionEngine
engine = QuantConvictionEngine(account_value=390, max_drawdown=0.20)
# Analyze with regime and VRP adjustments
result = engine.analyze("AAPL", "bull_put", regime_aware=True, vol_aware=True)
print(f"Final score: {result.final_score}")
print(f"Regime: {result.regime}")
print(f"VRP: {result.vrp_signal.vrp if result.vrp_signal else 'N/A'}")
# Calculate position size
sizing = engine.calculate_position(result, pop=0.65, max_loss=80, win_amount=40)
print(f"Contracts: {sizing['contracts']}")
# Run backtest validation
report = engine.run_backtest(["SPY", "QQQ"], "2022-01-01", "2024-01-01")
print(f"Recommendation: {report.recommendation}")Combining orthogonal signals reduces false-positive rate compared to single-indicator strategies (Pring, 2002; Murphy, 1999).
conviction-engine/
āāā scripts/
ā āāā conviction-engine # CLI wrapper (bash)
ā āāā spread_conviction_engine.py # Core engine (vertical spreads)
ā āāā multi_leg_strategies.py # Multi-leg extensions
ā āāā quantitative_integration.py # Unified quantitative interface
ā āāā regime_detector.py # VIX-based regime classification
ā āāā vol_forecaster.py # GARCH volatility forecasting
ā āāā enhanced_kelly.py # Drawdown-constrained Kelly sizing
ā āāā backtest_validator.py # Walk-forward validation
ā āāā quant_scanner.py # Quantitative options scanner
ā āāā market_scanner.py # Technical market scanner
ā āāā calculator.py # Black-Scholes & POP calculator
ā āāā position_sizer.py # Kelly position sizing
ā āāā chain_analyzer.py # IV surface analyzer
ā āāā options_math.py # Core mathematical models
ā āāā setup-venv.sh # Environment setup
āāā tests/ # Unit tests
ā āāā test_regime_detector.py
ā āāā test_vol_forecaster.py
ā āāā test_enhanced_kelly.py
ā āāā test_backtest_validator.py
ā āāā run_tests.py
āāā SKILL.md # This documentationThis separation keeps concerns clean while avoiding duplication.
clawhub install options-spread-conviction-engineThe skill automatically creates a virtual environment and installs:
Note: On Python 3.14+, the engine runs in pure Python mode without numba. Performance is slightly reduced but all functionality works correctly.
The engine includes two distinct scanning tools for different trading philosophies:
Automates the search for high-conviction plays across entire stock universes using technical indicators (Ichimoku, RSI, MACD, BB).
# Scan S&P 500 for high-conviction technical setups
python3 scripts/market_scanner.py --universe sp500A mathematically-rigorous scanner that ignores technical indicators in favor of market microstructure and probability.
# Maximize POP (Probability of Profit) for SPY
python3 scripts/quant_scanner.py SPY --mode pop
# High-expectancy (EV) plays with specific DTE
python3 scripts/quant_scanner.py AAPL TSLA --mode ev --min-dte 30The integrated toolchain includes:
Black-Scholes options pricing with support for:
Kelly criterion position sizing adapted for small accounts:
from position_sizer import calculate_position
result = calculate_position(
account_value=390,
max_loss_per_spread=80,
win_amount=40,
pop=0.65,
)
# Returns: contracts, total_risk, recommendation, reasonscripts/conviction-engine ā Main CLI wrapper for conviction enginescripts/spread_conviction_engine.py ā Core engine (vertical spreads)scripts/multi_leg_strategies.py ā Multi-leg extensions (v2.0.0)scripts/market_scanner.py ā Automated market scanner for EXECUTE playsscripts/calculator.py ā Black-Scholes pricing, Greeks, Monte Carlo POPscripts/position_sizer.py ā Kelly criterion position sizingscripts/setup-venv.sh ā Environment setupdata/sp500_tickers.txt ā S&P 500 constituentsdata/ndx100_tickers.txt ā Nasdaq 100 constituentsassets/ ā Documentation and examplesMIT ā Part of the Financial Toolkit for OpenClaw
Generated Mar 1, 2026
A retail trader uses the engine to identify high-conviction vertical spreads (bull put, bear call, bull call, bear put) based on technical indicators like Ichimoku, RSI, and MACD. They input a ticker like AAPL, and the engine scores strategies, recommending entry points for mean-reversion credit spreads or breakout debit spreads, helping them execute trades with quantified risk.
A hedge fund employs the engine to automate iron condor, butterfly, and calendar spread trades. It leverages regime detection via VIX and GARCH volatility forecasting to adjust positions, using walk-forward backtesting for validation. The engine's scoring of IV term structure and technical indicators optimizes non-directional theta harvesting in volatile markets.
A financial advisor uses the engine to generate income or hedge positions for clients. They analyze tickers to score iron condors for premium selling in range-bound markets or calendar spreads for theta advantage, ensuring drawdown-constrained Kelly sizing to manage risk while enhancing portfolio returns.
A market maker utilizes the engine to assess volatility regimes and IV term structures, scoring strategies like butterflies for pinning plays during low volatility. This helps in managing inventory by identifying opportunities to profit from volatility compression or inverted term structures, improving liquidity provision efficiency.
An online trading education platform integrates the engine as a learning tool. Students input tickers to see real-time scoring of seven strategies, with detailed breakdowns of indicator weights and triggers, helping them understand how technical analysis and IV dynamics influence options spread selection.
Offer a monthly subscription service where retail traders access the engine via a web interface or API. Features include real-time ticker analysis, strategy scoring, and backtesting reports. Revenue is generated through tiered plans based on usage limits and advanced analytics.
License the engine to hedge funds, banks, and trading firms as a white-label solution. Provide custom integrations with their existing trading platforms, along with support for high-frequency data feeds and compliance reporting. Revenue comes from annual licensing fees and maintenance contracts.
Deploy a free version with basic analysis for vertical spreads, attracting a broad user base. Monetize through premium upgrades offering multi-leg strategy scoring, advanced backtesting, and API access. Additional revenue streams include affiliate partnerships with brokerage platforms.
š¬ Integration Tip
Ensure Python3 and dependencies like jq and yahoo-finance2 are installed via the provided scripts; integrate with trading platforms by calling the engine's API for real-time strategy scoring and position sizing.
Analyze stocks and cryptocurrencies using Yahoo Finance data. Supports portfolio management, watchlists with alerts, dividend analysis, 8-dimension stock scoring, viral trend detection (Hot Scanner), and rumor/early signal detection. Use for stock analysis, portfolio tracking, earnings reactions, crypto monitoring, trending stocks, or finding rumors before they hit mainstream.
Get stock prices, quotes, fundamentals, earnings, options, dividends, and analyst ratings using Yahoo Finance. Uses yfinance library - no API key required.
Yahoo Finance (yfinance) powered stock analysis skill: quotes, fundamentals, ASCII trends, high-resolution charts (RSI/MACD/BB/VWAP/ATR), plus optional web a...
Become an autonomous prediction market trader on Polymarket with AI-powered analysis and a performance-backed token on Base. Trade real markets, build a track record, and let the buyback flywheel run.
Get cryptocurrency token price and generate candlestick charts via CoinGecko API or Hyperliquid API. Use when user asks for token price, crypto price, price chart, or cryptocurrency market data.
Trade and monitor Hyperliquid perpetual futures. Check balances, view positions with P&L, place/cancel orders, execute market trades. Use when the user asks about Hyperliquid trading, portfolio status, crypto positions, or wants to execute trades on Hyperliquid.