Skip to main content

​
Overview

The Strategy Recommender endpoint analyzes real-time options chains and recommends statistically advantageous spread strategies based on your market bias and risk profile. It uses Theta Gang methodology to identify optimal trades.

​
Get Strategy Recommendations

curl "http://localhost:8000/api/options/recommend/AAPL?bias=neutral&risk_profile=balanced&min_dte=30&max_dte=60"
​
ticker
string
required
Stock ticker symbol (e.g., “AAPL”, “SPY”, “TSLA”)
​
bias
string
default:"neutral"
Market direction bias:
  • bullish - Expect price to rise
  • neutral - Expect price to stay range-bound
  • bearish - Expect price to fall
​
risk_profile
string
default:"balanced"
Risk tolerance affecting strategy selection:
  • conservative - Higher probability of profit, lower credit
  • balanced - Moderate risk/reward
  • aggressive - Lower probability, higher credit potential
​
min_dte
integer
default:30
Minimum days to expiration for option legs. Must be >= 1.
​
max_dte
integer
default:60
Maximum days to expiration for option legs. Must be 180 or less.

​
Response

​
status
string
Status: "success" or "error"
​
ticker
string
Ticker symbol in uppercase
​
bias
string
The market bias used for recommendations
​
risk_profile
string
The risk profile used
​
spot
float
Current spot price of the underlying
​
analyzed_expirations
array
List of expiration dates analyzed (typically one date for consistency)
​
recommendations
array
Array of recommended strategy objects

​
Example Response

{
  "status": "success",
  "ticker": "AAPL",
  "bias": "neutral",
  "risk_profile": "balanced",
  "spot": 175.43,
  "analyzed_expirations": ["2024-12-20"],
  "recommendations": [
    {
      "strategy_name": "Iron Condor",
      "strategy_type": "credit",
      "expected_credit": 125.00,
      "max_profit": 125.00,
      "max_loss": -375.00,
      "probability_of_profit": 68.5,
      "break_even": [168.75, 181.25],
      "risk_reward_ratio": 3.0,
      "legs": [
        {
          "type": "put",
          "action": "buy",
          "strike": 165.0,
          "expiration": "2024-12-20",
          "premium": 0.95,
          "delta": -0.12,
          "theta": 0.08,
          "volume": 450,
          "open_interest": 1250
        },
        {
          "type": "put",
          "action": "sell",
          "strike": 170.0,
          "expiration": "2024-12-20",
          "premium": 2.20,
          "delta": -0.25,
          "theta": 0.15,
          "volume": 890,
          "open_interest": 2100
        },
        {
          "type": "call",
          "action": "sell",
          "strike": 180.0,
          "expiration": "2024-12-20",
          "premium": 2.30,
          "delta": 0.28,
          "theta": 0.16,
          "volume": 1120,
          "open_interest": 3400
        },
        {
          "type": "call",
          "action": "buy",
          "strike": 185.0,
          "expiration": "2024-12-20",
          "premium": 1.05,
          "delta": 0.15,
          "theta": 0.09,
          "volume": 650,
          "open_interest": 1800
        }
      ],
      "net_greeks": {
        "delta": 1.20,
        "theta": 9.50,
        "gamma": -2.10,
        "vega": -18.40
      },
      "description": "Iron Condor is a neutral strategy that profits from low volatility. Sell OTM put and call spreads to collect premium. Best when expecting the stock to stay within a range."
    },
    {
      "strategy_name": "Short Strangle",
      "strategy_type": "credit",
      "expected_credit": 185.00,
      "max_profit": 185.00,
      "max_loss": -99999.0,
      "probability_of_profit": 62.0,
      "break_even": [168.15, 182.85],
      "risk_reward_ratio": 999.0,
      "legs": [
        {
          "type": "put",
          "action": "sell",
          "strike": 170.0,
          "expiration": "2024-12-20",
          "premium": 2.20,
          "delta": -0.25,
          "theta": 0.15,
          "volume": 890,
          "open_interest": 2100
        },
        {
          "type": "call",
          "action": "sell",
          "strike": 180.0,
          "expiration": "2024-12-20",
          "premium": 2.30,
          "delta": 0.28,
          "theta": 0.16,
          "volume": 1120,
          "open_interest": 3400
        }
      ],
      "net_greeks": {
        "delta": 0.60,
        "theta": 12.40,
        "gamma": -5.80,
        "vega": -28.20
      },
      "description": "Short Strangle profits from time decay and low volatility. Undefined risk - requires careful monitoring. Higher credit than Iron Condor but more risk."
    }
  ]
}

​
Strategy Types by Bias

Strategies recommended for bias="neutral":
  • Iron Condor - Defined risk, moderate credit
  • Short Strangle - Undefined risk, higher credit
  • Iron Butterfly - Tight profit zone, highest credit
  • Calendar Spread - Volatility play

​
Liquidity Filtering

The recommender only considers liquid options:
Minimum Liquidity Requirements:
  • Conservative/Balanced: Open Interest >= 50, Volume >= 10
  • Aggressive: Open Interest >= 20, Volume >= 5
Illiquid options are filtered out to ensure tradeable recommendations.

​
Error Responses

​
400
error
No price data or insufficient liquidity
{
  "detail": "No se pudo recuperar precio Spot para XYZ"
}
or
{
  "detail": "No hay contratos con suficiente liquidez (OI >= 50 y Volumen >= 10) en la fecha 2024-12-20."
}
​
404
error
No expirations found
{
  "detail": "No se encontraron fechas de expiración"
}
​
500
error
Internal error during processing
{
  "detail": "Error message"
}

​
Implementation Notes

Expiration Consistency: The recommender uses a single expiration date for all legs to ensure strategy integrity (e.g., Iron Condor requires all 4 legs to expire on the same date).
DTE Fallback: If no expirations fall within min_dte to max_dte, the recommender selects the expiration closest to 45 DTE (the “sweet spot” for theta decay).

​
Use Cases

  • Strategy Discovery: Find trades you might not have considered
  • Backtesting Ideas: Get structured strategies to backtest
  • Education: Learn different spread constructions
  • Quick Setup: Copy recommended legs directly into your strategy builder
  • Risk-Adjusted Trading: Match strategies to your risk tolerance

​
Example Workflows

curl "http://localhost:8000/api/options/recommend/SPY?bias=neutral&risk_profile=conservative&min_dte=45&max_dte=60"
Get high-probability credit strategies for monthly income.
curl "http://localhost:8000/api/options/recommend/TSLA?bias=bullish&risk_profile=aggressive&min_dte=20&max_dte=40"
Get higher-credit bullish strategies with lower probability but bigger payoff.
curl "http://localhost:8000/api/options/recommend/AAPL?bias=neutral&risk_profile=balanced&min_dte=30&max_dte=50"
Get well-balanced Iron Condors and similar range-bound strategies.

Build docs developers (and LLMs) love

Get started for freeTalk to us