---
id: staskh/trading_skills/ib-find-short-roll
version: "5b588dfd"
license: MIT
install: manual
updated: 2026-07-20
---

# ib-find-short-roll — Analyze roll opportunities for existing short options or identify best covered calls/puts to open against long stock. The skill connects to Interactive Brokers via TWS or IB Gateway, evaluates candidates across multiple expirations, and uses IV-aware strike bands to surface relevant alternatives tailored to market conditions.

Publisher: staskh · Stars: 299 · Updated: 2026-07-20

Install (manual): `git clone https://github.com/staskh/trading_skills`

## SKILL.md

# 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.

## IB Connection

TWS or IB Gateway must be running locally with API enabled:
- **Paper trading** — port 7497
- **Live trading** — port 7496
- **`IB_PORT` env var** — default port when `--port` is omitted (e.g. `IB_PORT=4001` for a Gateway container). Precedence: `--port` flag > `IB_PORT` > built-in default. Set it in the shell or a `.env` file.

**Port fallback:** If the configured port fails, automatically retry on the other port.
If the retry succeeds, save to memory which account type worked (live/paper) and reuse it for all IB skill calls in this and future sessions — until the user explicitly asks for the other account.
If both ports fail, ask the user to verify that TWS or IB Gateway is running with API access enabled.

## 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.

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

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

1. **If short option position exists** (`mode: "roll"`): Analyzes roll candidates to different expirations/strikes
2. **If long option position exists** (`mode: "spread"`): Finds best short call/put to create a vertical spread
3. **If long stock exists** (`mode: "new_short"`): Finds best covered call (or protective put) to open
4. **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: 7497 for paper trading)
- `--account` - Specific account ID (optional)
- `--iv-multiplier` - Expected-move multiplier for strike band width (default: 2.0); increase for high-IV names to surface wider roll candidates

## 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` (includes `iv` and `delta` from IB greeks), `buy_to_close`, `roll_candidates` (dict of expiry -> candidates), `iv_multiplier`
- **spread**: `long_option`, `right`, `candidates_by_expiry`
- **new_short**: `long_position`, `right`, `candidates_by_expiry`, `iv_multiplier`

### Strike Band Logic (roll and new_short modes)
The strike search window is IV-aware: `half_band = iv_multiplier × ATM_IV × spot × √(T/365)` where T is the DTE of the nearest roll expiry. For roll mode, ATM IV comes from IB model greeks on the current position's quote; if unavailable, it is estimated from the option mid-price using the Brenner-Subrahmanyam approximation. For new_short mode, a conservative default IV of 30% is used. This makes the band automatically wider for high-IV underlyings without requiring a manual override.

## Example Usage

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

# 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`


## Timezone

All timestamps and time-based calculations must use the `America/New_York` timezone. All JSON output must include `generated_at` (NY time string) and `data_delay` fields.

[View on SkillFed](https://skillfed.io/staskh/trading_skills/ib-find-short-roll) · [View on GitHub](https://github.com/staskh/trading_skills)