What prerequisites are required?

TWS or IB Gateway running locally with API enabled; use port 7496 for live trading or 7497 for paper trading.

What does the mode field indicate?

mode can be 'roll' (analyzes roll candidates for short positions), 'spread' (finds best short against a long option to form a spread), or 'new_short' (finds a covered call or protective put against long stock).

What output does the script produce?

JSON to stdout containing mode, symbol, underlying_price, expirations_analyzed, and mode-specific fields such as current_position, roll_candidates, long_option, or candidates_by_expiry.

ib-find-short-roll

Scanned

npx machina-cli add skill staskh/trading_skills/ib-find-short-roll --openclaw

Files (1)

SKILL.md

3.2 KB

IB Find Short Roll

Analyze roll options for short positions or find best short options to open against long stock using real-time data from Interactive Brokers.

Prerequisites

User must have TWS or IB Gateway running locally with API enabled:

Paper trading: port 7497
Live trading: port 7496

Instructions

Step 1: Gather Data

Note: If uv is not installed or pyproject.toml is not found, replace uv run python with python in all commands below.

uv run python scripts/roll.py SYMBOL [--strike STRIKE] [--expiry YYYYMMDD] [--right C|P] [--port PORT] [--account ACCOUNT]

The script returns JSON to stdout with all position and candidate data.

Step 2: Format Report

Read templates/markdown-template.md for formatting instructions. Generate a markdown report from the JSON data and save to sandbox/.

Step 3: Report Results

Present key findings to the user: recommended position, credit/debit, and the saved report path.

Behavior

If short option position exists (mode: "roll"): Analyzes roll candidates to different expirations/strikes
If long option position exists (mode: "spread"): Finds best short call/put to create a vertical spread
If long stock exists (mode: "new_short"): Finds best covered call (or protective put) to open
If none of the above: Returns error (use --strike/--expiry to specify manually)

Arguments

SYMBOL - Ticker symbol (e.g., GOOG, AAPL, TSLA)
--strike - Current short strike price (optional, auto-detects from portfolio)
--expiry - Current short expiration in YYYYMMDD format (optional, auto-detects)
--right - Option type: C for call, P for put (default: C)
--port - IB port (default: 7496 for live trading)
--account - Specific account ID (optional)

JSON Output

The script outputs JSON with mode field indicating the analysis type:

Common Fields

success - Boolean
generated - Timestamp
mode - "roll", "spread", or "new_short"
symbol - Ticker
underlying_price - Current stock price
earnings_date - Next earnings date or null
expirations_analyzed - List of expiry dates checked

Mode-specific Fields

roll: current_position, buy_to_close, roll_candidates (dict of expiry -> candidates)
spread: long_option, right, candidates_by_expiry
new_short: long_position, right, candidates_by_expiry

Example Usage

# Auto-detect GOOG position (short option, long option, or long stock)
uv run python scripts/roll.py GOOG --port 7496

# Specify exact short position to roll
uv run python scripts/roll.py GOOG --strike 350 --expiry 20260206 --right C

# Find short call to sell against long call (vertical spread)
uv run python scripts/roll.py AUR --right C

# Find covered put for long stock
uv run python scripts/roll.py TSLA --right P

Dependencies

ib-async
yfinance

Source

git clone https://github.com/staskh/trading_skills/blob/main/.claude/skills/ib-find-short-roll/SKILL.mdView on GitHub

Overview

IB Find Short Roll analyzes roll options for existing short positions or the best short calls/puts to open against long stock using real-time IB data. It helps traders manage option positions, roll efficiently, and explore covered-call or spread opportunities.

How This Skill Works

The tool uses a locally running TWS or IB Gateway API (port 7496/7497) to pull live price and portfolio data, then analyzes mode: roll (short positions), spread (long options), or new_short (long stock). It outputs a JSON payload with position details and candidate contracts, and a markdown report is generated for review.

When to Use It

You need to roll a current short option position and compare expirations/strikes
You want to create a vertical spread by selling a short call/put against a long option
You want to open a new position by selling a covered call against long stock
You want a structured report with recommended actions and credit/debit estimates
You want to guide manual entry by specifying symbol/strike/expiry to fetch candidates

Quick Start

Step 1: Gather Data - Run uv run python scripts/roll.py SYMBOL [--strike STRIKE] [--expiry YYYYMMDD] [--right C|P] [--port PORT] [--account ACCOUNT].
Step 2: Format Report - Read templates/markdown-template.md for formatting and save the report to sandbox/.
Step 3: Report Results - Review the recommended position, credit/debit, and the saved report path.

Best Practices

Ensure IB API is enabled and you’re using the correct port (7496 for live, 7497 for paper).
Supply SYMBOL and optional --strike/--expiry to tailor results.
Review the generated markdown report in sandbox/ before placing any trades.
Compare roll candidates across expirations and assess risk/reward tradeoffs.
Consider earnings dates, events, and IV when selecting a roll or new_short strategy.

Example Use Cases

Auto-detect a short AAPL call and roll it to a later expiry with a favorable credit.
Find a best short call to open against long stock TSLA to create a vertical spread.
Identify a profitable roll from 2025-03-21 to 2025-04-18 for GOOG short put.
Open a covered call for MSFT using long stock and assess potential credit.
Specify a symbol with --strike and --expiry to fetch targeted roll candidates when you know exact parameters.

Frequently Asked Questions

Add this skill to your agents