Automated Wheel Strategy

Welcome to the Wheel Strategy automation project! This script is designed to help you trade the classic "wheel" options strategy with as little manual work as possible using the Alpaca Trading API.

---

Strategy Logic

Here's the basic idea:

1. Sell cash-secured puts on stocks you wouldn't mind owning.
2. If you get assigned, buy the stock.
3. Then sell covered calls on the stock you own.
4. Keep collecting premiums until the stock gets called away.
5. Repeat the cycle!

This code helps pick the right puts and calls to sell, tracks your positions, and automatically turns the wheel to the next step.

---

How to Run the Code

1. Clone the repository:

   git clone https://github.com/alpacahq/options-wheel.git
   cd options-wheel
   

2. Create a virtual environment using uv:

   uv venv
   source .venv/bin/activate  # Or `.venv\Scripts\activate` on Windows
   

3. Install the required packages:

   uv pip install -e .
   

4. Set up your API credentials:

   Create a .env file in the project root with the following content:

   ALPACA_API_KEY=your_public_key
   ALPACA_SECRET_KEY=your_private_key
   IS_PAPER=true  # Set to false if using a live account
   

   Your credentials will be loaded from .env automatically.

5. Choose your symbols:

   The strategy trades only the symbols listed in config/symbol_list.txt. Edit this file to include the tickers you want to run the Wheel strategy on — one symbol per line. Choose stocks you'd be comfortable holding long-term.

6. Configure trading parameters:

   Adjust values in config/params.py to customize things like buying power limits, options characteristics (e.g., greeks / expiry), and scoring thresholds. Each parameter is documented in the file.

7. Run the strategy

   Run the strategy (which assumes an empty or fully managed portfolio):

   run-strategy
   

   Tip: On your first run, use --fresh-start to liquidate all existing positions and start clean.

   There are two types of logging:

   • Strategy JSON logging (--strat-log): Always saves detailed JSON files to disk for analyzing strategy performance.

   • Runtime logging (--log-level and --log-to-file): Controls console/file logs for monitoring the current run. Optional and configurable.

   Flags:

   • --fresh-start — Liquidate all positions before running (recommended first run).
   • --strat-log — Enable strategy JSON logging (always saved to disk).
   • --log-level LEVEL — Set runtime logging verbosity (default: INFO).
   • --log-to-file — Save runtime logs to file instead of console.

   Example:

   run-strategy --fresh-start --strat-log --log-level DEBUG --log-to-file
   

   For more info:

   run-strategy --help
   

---

What the Script Does

• Checks your current positions to identify any assignments and sells covered calls on those.
• Filters your chosen stocks based on buying power (you must be able to afford 100 shares per put).
• Scores put options using core.strategy.score_options(), which ranks by annualized return discounted by the probability of assignment.
• Places trades for the top-ranked options.

---

Notes

• Account state matters: This strategy assumes full control of the account — all positions are expected to be managed by this script. For best results, start with a clean account (e.g. by using the --fresh-start flag).
• One contract per symbol: To simplify risk management, this implementation trades only one contract at a time per symbol. You can modify this logic in core/strategy.py to suit more advanced use cases.
• The user agent for API calls defaults to OPTIONS-WHEEL to help Alpaca track usage of runnable algos and improve user experience. You can opt out by adjusting the USER_AGENT variable in core/user_agent_mixin.py — though we kindly hope you’ll keep it enabled to support ongoing improvements.
• Want to customize the strategy? The core/strategy.py module is a great place to start exploring and modifying the logic.

---

Automating the Wheel

Running the script once will only turn the wheel a single time. To keep it running as a long-term income strategy, you'll want to automate it to run several times per day. This can be done with a cron job on Mac or Linux.

Setting Up a Cron Job (Mac / Linux)

1. Find the full path to the run-strategy command by running:

   which run-strategy
   

   This will output something like:

   /Users/yourname/.local/share/virtualenvs/options-wheel-abc123/bin/run-strategy
   

2. Open your crontab for editing:

   crontab -e
   

3. Add the following lines to run the strategy at 10:00 AM, 1:00 PM, and 3:30 PM on weekdays:

   0 10 * * 1-5 /full/path/to/run-strategy >> /path/to/logs/run_strategy_10am.log 2>&1
   0 13 * * 1-5 /full/path/to/run-strategy >> /path/to/logs/run_strategy_1pm.log 2>&1
   30 15 * * 1-5 /full/path/to/run-strategy >> /path/to/logs/run_strategy_330pm.log 2>&1
   

   Replace /full/path/to/run-strategy with the output from the which run-strategy command above. Also replace /path/to/logs/ with the directory where you'd like to store log files (create it if needed).

---

Test Results

To validate the code mechanics, the strategy was tested in an Alpaca paper account over the course of two weeks (May 14 – May 28, 2025). A full report and explanation of each decision point can be found in reports/options-wheel-strategy-test.pdf. A high-level summary of the trading results is given below.

Premiums Collected

| Underlying | Expiry | Strike | Type | Date Sold | Premium Collected | | ---------- | ---------- | ------ | ---- | ---------- | ----------------- | | PLTR | 2025-05-23 | 124 | P | 2025-05-14 | $261.00 | | NVDA | 2025-05-30 | 127 | P | 2025-05-14 | $332.00 | | MP | 2025-05-23 | 20 | P | 2025-05-14 | $28.00 | | AAL | 2025-05-30 | 11 | P | 2025-05-14 | $20.00 | | INTC | 2025-05-30 | 20.50 | P | 2025-05-14 | $33.00 | | CAT | 2025-05-16 | 345 | P | 2025-05-14 | $140.00 | | AAPL | 2025-05-23 | 200 | P | 2025-05-19 | $110.00 | | DLR | 2025-05-30 | 165 | P | 2025-05-20 | $67.00 | | AAPL | 2025-05-30 | 202.50 | C | 2025-05-27 | $110.00 | | MP | 2025-05-30 | 20.50 | C | 2025-05-27 | $12.00 | | PLTR | 2025-05-30 | 132 | C | 2025-05-27 | $127.00 |

Total Premiums Collected: $1,240.00

---

Total PnL (Change in Account Liquidating Value)

| Metric | Value | | ------------------------ | --------------- | | Starting Balance | $100,000.00 | | Ending Balance | $100,951.89 | | Net PnL | +$951.89 |

---

Disclaimer

These results are based on historical, simulated trading in a paper account over a limited timeframe and do not represent actual live trading performance. They are provided solely to demonstrate the mechanics of the strategy and its ability to automate the Wheel process in a controlled environment. Past performance is not indicative of future results. Trading in live markets involves risk, and there is no guarantee that future performance will match these simulated results.

---

Core Strategy Logic

The core logic is defined in core/strategy.py.

• Stock Filtering: The strategy filters underlying stocks based on available buying power. It fetches the latest trade prices for each candidate symbol and retains only those where the cost to buy 100 shares (price × 100) is within your buying power limit. This keeps trades within capital constraints and can be extended to include custom filters like volatility or technical indicators.

• Option Filtering: Put options are filtered by absolute delta, which must lie between DELTA_MIN and DELTA_MAX, by open interest (OPEN_INTEREST_MIN) to ensure liquidity, and by yield (between YIELD_MIN and YIELD_MAX). For short calls, the strategy applies a minimum strike price filter (min_strike) to ensure the strike is above the underlying purchase price. This helps avoid immediate assignment and locks in profit if the call is assigned.

• Option Scoring: Options are scored to estimate their attractiveness based on annualized return, adjusted for assignment risk. The score formula is:

  score = (1 - |Δ|) × (250 / (DTE + 5)) × (bid price / strike price)

  Where:

  • $\Delta$ = option delta (a rough proxy for the probability of assignment)
  • DTE = days to expiration
  • The factor 250 approximates the number of trading days in a year
  • Adding 5 days to DTE smooths the score for near-term options

• Option Selection: From all scored options, the strategy picks the highest-scoring contract per underlying symbol to promote diversification. It filters out options scoring below SCORE_MIN and returns either the top N options or all qualifying options.

---

Ideas for Customization

Stock Picking

• Use technical indicators such as moving averages, RSI, or support/resistance levels to identify stocks likely to remain range-bound — ideal for selling options in the Wheel strategy.
• Incorporate fundamental filters like earnings growth, dividend history, or volatility to select stocks you’re comfortable holding long term.

Scoring Function for Puts / Calls

• Modify the scoring formula to weight factors differently or separately for puts vs ca