/ib_0dte

name: ib_0dte
description: Find and place the best 0DTE (zero-days-to-expiration) credit spreads from Interactive Brokers. Default execution route is the EMA9/EMA21 + VIX/VXN regime strategy (ema_vix_0dte.py), which auto-selects bull_put or bear_call from a bare EMA cross and skips the trade when the vol index is elevated (VXN ≥ 35 for NDX/QQQ, VIX ≥ 20 otherwise). Optional --rr-gate and --time-gate add red→red and bar-timing confirmation. Supports cash-settled indices (SPX, NDX, RUT, VIX) and any optionable stock/ETF. Manual spread type override is available via zero_dte.py. Requires TWS or IB Gateway running locally.
dependencies: ["trading-skills"]

IB 0DTE Credit Spread Finder & Executor

**Default execution route: `ema_vix_0dte.py`** — the EMA9/EMA21 + VIX/VXN regime strategy. It reads the 30-min IB bars, checks the vol index (VXN ≥ 35 for NDX/QQQ, VIX ≥ 20 otherwise), and auto-selects `bull_put` or `bear_call` from a bare EMA cross (or skips entirely) before delegating to the spread finder. Optional `--rr-gate` and `--time-gate` add confirmation. Use this unless the user explicitly requests a manual spread type.

`zero_dte.py` is the manual override when the user specifies `--type bear_call`, `--type bull_put`, or `--type iron_condor` directly.

Both scripts share the same spread-finding engine (find → propose → execute on `--execute`) and all the same flags. All data comes from IBKR.

Supports cash-settled indices (**SPX, NDX, RUT, VIX, XSP, DJX**) — which trade as `Index` contracts on their home exchange — as well as any optionable stock or ETF.

Prerequisites

TWS or IB Gateway running locally with the API enabled:

• Paper trading: port 7497 (default)
• Live trading: port 7496

Index options require the appropriate **index-options market-data entitlement** (separate from equity/ETF data). Without it, index quotes will not populate.

Instructions

EMA + VIX/VXN Strategy (recommended — fully automatic signal)

The script checks the vol index, reads the 30-min bars, determines bull_put vs bear_call from the EMA9/EMA21 cross, then calls the spread finder automatically. By **default it runs a bare EMA cross with no bar-timing or red→red gate**, so it can be run at any time of day. Opt into the confirmation gates per run.

# Dry run (propose only, no order placed) — bare EMA cross.
# Budget auto-sizes to 50% of the account's excess liquidity.
uv run python scripts/ema_vix_0dte.py NDX --account U790497 --port 7496

# With both confirmation gates on (original 10:30-ET behavior)
uv run python scripts/ema_vix_0dte.py NDX --account U790497 --port 7496 \
    --rr-gate --time-gate

# Live execution
uv run python scripts/ema_vix_0dte.py NDX --account U790497 --port 7496 --execute

# Explicit budget override (skips the excess-liquidity lookup)
uv run python scripts/ema_vix_0dte.py NDX --budget 50000 --port 7496 \
    --account U790497 --execute

# SPX variant
uv run python scripts/ema_vix_0dte.py SPX --account U790497 --port 7496 --execute

**Vol index:** NDX/QQQ are gated on **VXN** (CBOE Nasdaq-100 Volatility Index — the correct vol gauge for a Nasdaq-100 trade); all other symbols on **VIX**. The default cutoff is **per-index — VXN 35, VIX 20** (VXN typically prints several points above VIX for the same regime). The index used is echoed as `vol_index` in the output; the `vix_*` fields hold that index's readings.

The gate is **dual**: both the intraday reading and the **prior-day close** must sit below the cutoff, since a market recovering from a high-vol close is still fragile. Both come from IB (`vix_source: "ib"`) — one decision is never assembled from two data sources. Without both readings the run stands down rather than guessing (`signal: "VOL-UNAVAILABLE"`).

Signal logic (default — exits early with `success: false` and a reason on skip): 1. **No vol reading** (intraday or prior-day missing) → no trade (`signal: "VOL-UNAVAILABLE"`) 2. **Vol index ≥ cutoff** (VXN ≥ 35 for NDX/QQQ, else VIX ≥ 20, either reading) → no trade (`signal: "VIX-SKIP"`) 3. **EMA9 last crossed above EMA21** → `bull_put` (`signal: "EMA-Up"`) 4. **EMA9 last crossed below EMA21** → `bear_call` (`signal: "EMA-Dn"`)

Optional confirmation gates (both **off** by default):

• `--rr-gate` — an EMA-down becomes a Bear Call only if **today's two most recently

closed bars are both red** (`signal: "EMA-Dn+RR"`); otherwise no trade (`"EMA-Dn-no-RR"`). The confirmation tracks momentum at the moment of the run, so it means the same thing at 10:30 as at 15:00. A bar still in progress cannot confirm anything and is not counted.

• `--time-gate` — require today's 9:30 + 10:00 ET bars (run at 10:30 ET or later)

and anchor the EMA-cross lookback to the 10:00 ET bar. Without it the lookback anchors to the latest available bar.

Additional flags:

• `--vix-threshold N` — override the vol-index cutoff (default: per-index — VXN 35, VIX 20)
• `--target-delta 0.12` — short-leg delta target (default: 0.12, ≈1.5% OTM at VIX<20)
• All other `zero_dte.py` flags (`--max-width`, `--gex`, `--stop-mult`, etc.) pass through

Manual spread finder (explicit type)

Optionally confirm a same-day (0DTE) expiry exists first:

uv run python scripts/zero_dte.py SYMBOL --expiries

Then find the best spreads (dry run — proposes only, places nothing):

uv run python scripts/zero_dte.py SYMBOL --type bear_call --budget 2000

Execute the chosen spread (places a live combo order):

uv run python scripts/zero_dte.py SYMBOL --type bear_call --budget 2000 \
    --account U1234567 --execute            # places the best pick
uv run python scripts/zero_dte.py SYMBOL --budget 2000 \
    --account U1234567 --execute --pick 2   # places the 2nd-ranked pick

Arguments

• `SYMBOL` — underlying (e.g. `SPX`, `NDX`, `RUT`, `VIX`, `AAPL`, `SPY`)
• `--type` — `bear_call` (default, bearish/neutral), `bull_put` (bullish/neutral), or `iron_condor` (neutral)
• `--budget` — max capital at risk in doll