ThetaGang

ThetaGang is an IBKR (Interactive Brokers) trading bot designed for portfolio automation. While it originated as an implementation of 'The Wheel' strategy, it has evolved into a configurable tool for managing diversified portfolios. It uses option writing (specifically puts) to harvest volatility, aiming to augment index-fund based portfolios by selling options instead of buying shares directly.

Key features include:

• Direct share rebalancing (buy-only and sell-only modes)
• Cash management via cash-equivalent funds
• VIX call hedging
• Regime-aware rebalancing gates
• Exchange-hours enforcement
• Automated option rolling

Follow these steps to set up a paper trading environment:

1. Download the sample configuration:

   curl -Lq https://raw.githubusercontent.com/brndnmtthws/thetagang/main/thetagang.toml -o ./thetagang.toml

2. Edit thetagang.toml to update the following required fields:
   • account.number
   • ibc.userid and ibc.password
   • ibc.tradingMode = "paper"
   • symbols.<SYMBOL>.weight allocations
3. If running locally (not Docker), ensure:
   • ibc.ibcIni points to your local config.ini
   • ib_async.logfile is a writable local path
   • database.path is relative to the config file location
4. Run a dry run to verify connectivity and configuration:

   thetagang --config ./thetagang.toml --dry-run

Install the ThetaGang package using pip to run the trading bot locally.

pip install thetagang

If you intend to run materially different trading strategies, it is strongly recommended to use separate IBKR accounts (such as separate linked sub-accounts) and fund them independently.

Because ThetaGang's decisions (buying power usage, position targeting, rebalancing logic, option rolls, cash management, and hedge logic) are applied at the account level, mixing different strategy styles in a single account can cause conflicting interactions and difficult-to-debug side effects.

Running ThetaGang via Docker is recommended. You must provide both an IBC configuration (config.ini) and a ThetaGang configuration (thetagang.toml).

Linux (using host networking)

docker run --rm -i --net host \
    -v ~/thetagang:/etc/thetagang \
    brndnmtthws/thetagang:main \
    --config /etc/thetagang/thetagang.toml

macOS/Windows (using port mapping)

On macOS/Windows, --net host is not supported. Use explicit port mapping and set watchdog.host to host.docker.internal in your config.

docker run --rm -i \
    -p 7497:7497 \
    -v ~/thetagang:/etc/thetagang \
    brndnmtthws/thetagang:main \
    --config /etc/thetagang/thetagang.toml

ThetaGang can be used alongside other strategies like PMCCs, Zebra, or stock replacement. However, ThetaGang will not manage long positions for these strategies; you must manage those manually.

To ensure ThetaGang continues to execute the short legs of your external strategies, you must set the following configuration:

write_when.calculate_net_contracts = true

To develop on ThetaGang locally, install the Python dependencies and pre-commit hooks using uv.

# Install the pre-commit hooks
uv run pre-commit install
# Run thetagang
uv run thetagang -h

If you are already running IB Gateway or TWS manually, you can bypass the IBC (Interactive Brokers Controller) management by using the --without-ibc flag.

When running in this mode, ensure your configuration file matches your manual gateway settings for:

• watchdog.host
• watchdog.port
• watchdog.clientId
• ib_async.api_response_wait_time (increase this if you have a slower connection)

thetagang --config ./thetagang.toml --without-ibc

Gating share rebalances based on a regime filter (choppiness and efficiency). If the regime passes, it rebalances based on a soft_band. A hard_band acts as a safety rail that triggers even if the regime filter fails.

Note: Run the script once per day when using this feature.

[regime_rebalance]
enabled = true
symbols = ["QQQ", "BTAL"]
lookback_days = 40
soft_band = 0.25  # +/-25% relative drift from target weight
hard_band = 0.50  # +/-50% relative drift from target weight
hard_band_rebalance_fraction = 1.0  # 1.0 = full to target, 0.5 = halfway
cooldown_days = 5
choppiness_min = 3.0
efficiency_max = 0.30
order_history_lookback_days = 30
shares_only = true  # disable option writes/rolls while rebalancing

Fine-tune how positions and contracts are handled.

• calculate_net_contracts: Enable for spread strategies (PMCCs, calendars).
• excess_only: (For calls) Write calls only on shares exceeding target allocation.
• no_trading: Temporarily disable trading for a specific symbol (monitor only).

[write_when]
calculate_net_contracts = true

[symbols.QQQ.calls]
excess_only = true

[symbols.TSLA]
no_trading = true

Fine-tune IBKR API behavior and set absolute caps on new contracts.

[ib_async]
api_response_wait_time = 60
logfile = "ib_async.log"

[target]
maximum_new_contracts = 10
maximum_new_contracts_percent = 0.5

ThetaGang can optimize idle cash by purchasing a specified fund (e.g., a short-term treasury ETF) when cash levels exceed a certain threshold. It can also sell the fund when cash falls below a threshold to maintain liquidity. By default, it uses VWAP (Volume Weighted Average Price) orders to minimize market impact.

Enable this in thetagang.toml using the [cash_management] section.

[cash_management]
enabled = true
fund = "SGOV"  # Default short-term treasury ETF
buy_threshold = 0.01  # Buy when cash > 1% of buying power
sell_threshold = 0.005  # Sell when cash < 0.5%

[cash_management.orders]
algo.strategy = "Vwap"  # Use VWAP for cash fund orders