From download to live trading, step by step.

1. What you need before you start

The bot runs on your own machine or server — a laptop for testing, a small always-on VPS for anything you leave running.

• Python 3.10 or newer, on macOS, Linux or Windows.
• Your TradeWorms licence key, from the purchase email or your dashboard.
• For live trading only: an account at your exchange or broker, and an API key you create yourself.
• About 500 MB of disk space and a stable internet connection.

2. Download your build

Sign in, open your dashboard, and press Download bot next to your licence. The link is single-use and expires after 15 minutes, so unzip it somewhere permanent rather than re-downloading it each time.

unzip tradeworms-pro.zip
cd tradeworms-pro
python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -r requirements.txt

3. Add your licence key

Copy the example config and paste your key into it. The key binds to this machine on first run — Starter and Pro allow one machine, Institutional allows ten.

cp config.example.yaml config.yaml

# config.yaml
license_key: "PRO-XXXXX-XXXXX-XXXXX-XXXXX"
license_server: "https://tradeworms.lovable.app"
live_trading: false

python -m tradeworms verify

• verify shows your tier and which features it unlocks.
• A successful check is cached for 7 days, so a short internet outage will not stop a running bot.
• Moving to a new machine? Ask support to reset the activation.

4. Connect your exchange or broker

Your credentials never go into the config file and never reach us. The config only names the environment variables that hold them.

# in config.yaml
venues:
  - id: binance
    kind: crypto            # crypto | forex | ibkr
    exchange: binance
    timeframe: "1h"
    symbols: ["BTC/USDT", "ETH/USDT"]
    testnet: true           # sandbox first: real plumbing, fake money
    api_key_env: TW_BINANCE_KEY
    api_secret_env: TW_BINANCE_SECRET

# in your shell
export TW_BINANCE_KEY=...
export TW_BINANCE_SECRET=...

• Create the API key with trading enabled and withdrawals disabled, restricted to your machine's IP address.
• Interactive Brokers: run TWS or IB Gateway, enable API access in its settings, and point the bot at 127.0.0.1 with the port it shows (7497 paper, 7496 live).
• MetaTrader 5 forex: install the MT5 terminal on the same machine and give the bot your login, server and password variable names.
• MetaTrader 4 forex: copy mt4-bridge/TradeWormsBridge.mq4 from your download into the terminal's MQL4/Experts folder, drag it onto any chart, allow live trading, and point the bot's files_dir at MQL4/Files/tradeworms. No password goes in the config — the bot uses the terminal you are already logged into.
• cTrader (including FxPro cTrader): open Settings > FIX API in the cTrader app and copy the host, ports, SenderCompID and FIX password into a ctrader venue. No terminal is needed, so this works on Windows, macOS and Linux. cTrader serves live prices but no history, so backtest from CSV files.

5. Choose and tune your strategy

Strategies are configured, not coded. Pick the ones your tier allows, set their parameters, and set the risk limits you are willing to live with.

strategies:
  - name: trend
    type: trend
    weight: 1.0
    params: { fast: 20, slow: 50, rsi_period: 14 }

risk:
  risk_per_trade_pct: 0.5       # of equity, per position
  stop_loss_pct: 2.0
  take_profit_pct: 4.0
  max_daily_loss_pct: 3.0       # stops trading for the day
  max_drawdown_pct: 15.0        # kill switch

• Starter: one strategy from trend-following, mean-reversion or grid.
• Pro: several at once with individual weights, plus pairs/stat-arb and volatility-adjusted sizing.
• Institutional: regime detection switches strategy sets automatically, across multiple accounts.

6. Backtest before you risk anything

Run the strategy over historical candles and read the drawdown, not just the return. Pro and Institutional add walk-forward testing and Monte Carlo robustness runs that show how fragile a result is.

python -m tradeworms backtest
python -m tradeworms backtest --csv-dir ./data     # your own candle files
python -m tradeworms backtest --walk-forward --monte-carlo

• A backtest is a hypothesis, not a forecast. Treat a great-looking curve with suspicion.
• Change one parameter at a time — tuning many at once fits the past, not the future.

7. Run in paper mode

This is the default. The bot reads real live market data and simulates fills, so you see real behaviour without real money. Leave it running for days or weeks, not minutes.

python -m tradeworms run

# alerts, if you want them
alerts:
  telegram_token_env: TW_TELEGRAM_TOKEN
  telegram_chat_id: "123456789"
  email_to: "you@example.com"

• State, logs and the trade journal are written to ./state.
• Pro and Institutional include a web dashboard with the equity curve, open positions and trade log.
• Institutional adds the live trading desk on port 8789: broker-reported balances, open positions marked to the current price, realised and unrealised P&L, and every execution fill with fee, slippage and order id. Enable it with live_dashboard.enabled: true. It is read-only and binds to your own machine.

8. Switch to live trading

Live orders go straight from your machine to your own account. Turning it on is deliberately a multi-step process.

# read-only: connects, reads balances and candles, places NO orders
python -m tradeworms live-check

# then, in config.yaml
live_trading: true
live:
  confirm_phrase: "I ACCEPT LIVE TRADING RISK"
  max_order_notional: 500
  max_orders_per_hour: 20
  max_open_positions: 5

python -m tradeworms run --live

• Without the exact confirmation phrase the bot refuses to place a live order.
• Do a full rehearsal on an exchange testnet or an IBKR paper port first — the same code path runs.
• Every order is checked against the size cap, the hourly limit and the open-position cap. Exits and the kill switch are never blocked.
• Start with caps far smaller than you think you need, and raise them only after watching real sessions.

9. Keep it running

Anything you leave unattended should run on a machine that does not sleep, and should tell you when something goes wrong.

# keep it alive across restarts (Linux)
sudo systemctl enable --now tradeworms

# compliance export (Institutional)
python -m tradeworms export-audit --out audit.csv

• Turn on Telegram or email alerts so you hear about fills, halts and errors.
• Check the daily loss limit and drawdown kill switch actually fired the way you expect, in paper mode, before you rely on them.
• Stop the bot with Ctrl+C; it closes cleanly and can cancel open orders on exit.