Live Trading Guide

The Trading Bot Framework can mirror your paper-trade portfolios (stored in PostgreSQL) to a live brokerage account. This is handled by a separate Live Trade Copier layer that runs independently of your bots.

---

🚀 Quick Start (5-Minute Dry Run)

You can verify the copier logic immediately without any complex setup.

1. Set Environment Variables:

   export DARWINEX_USERNAME="your_username"
   export DARWINEX_PASSWORD="your_password"
   export LIVETRADE_BOT_WEIGHTS='{"adaptivemeanreversionbot": 1.0}'
   export LIVETRADE_DRY_RUN=true
   

2. Run the Copier:

   uv run python tradingbot/livetrade_darwinex.py
   

3. Review the Log: Look for [DRY RUN] Would BUY/SELL ... lines to see what the copier would have done.

---

🔎 Inspect Account & Positions

Each broker module is runnable as a script and prints a summary of the configured account — equity, cash, and current open positions. Use it to sanity-check credentials and account IDs before running the copier:

# Collective2 — reads COLLECTIVE2_API_KEY + COLLECTIVE2_SYSTEM_ID
uv run python tradingbot/livetrade/collective2.py

# Interactive Brokers — reads IB_GATEWAY_HOST/PORT + IB_ACCOUNT_ID
# Connects read-only with IB_CLIENT_ID=19 by default so it won't collide
# with the cron client (17) or the vscode debug config (18).
uv run python tradingbot/livetrade/interactive_brokers.py

# eToro — reads ETORO_API_KEY + ETORO_USER_KEY + ETORO_DEMO
uv run python tradingbot/livetrade/etoro.py

# Darwinex — reads DARWINEX_USERNAME + DARWINEX_PASSWORD + DARWINEX_DEMO
uv run python tradingbot/livetrade/darwinex.py

All brokers expose print_account_summary() on the broker class, so you can call it from any script after constructing the broker.

---

📊 How Orders are Calculated

The copier does not just "blindly" copy signals; it synchronizes target state:

1. Per-Bot Normalization: For each bot in LIVETRADE_BOT_WEIGHTS, the current paper portfolio is converted to percentage weights (e.g., AAPL is 10% of Bot A).
2. Weighted Aggregation: Individual bot weights are aggregated based on your allocation (e.g., if Bot A is 60% of your capital, AAPL becomes 6% of your live total).
3. Broker Equity Sync: The copier fetches your Live Total Equity (Cash + Open Positions) from the broker.
4. Target Value: (Total Equity) × (Aggregate Target Weight) = Target USD Value for each symbol.
5. The Diff: The copier compares the Target Value vs. your Current Live Position value at the broker.
6. Order Generation: It generates the BUY or SELL orders needed to close the gap.
7. Safety Filters: Orders smaller than LIVETRADE_MIN_ORDER_USD are skipped to avoid excessive fees.

Price Fallback: If the broker cannot provide a real-time quote for a symbol, the framework falls back to yfinance to ensure calculations remain accurate.

Multi-Bot Weighting Example

If you have $100,000 in your live account and configure: LIVETRADE_BOT_WEIGHTS='{"adaptivemeanreversionbot": 0.6, "feargreedbot": 0.4}'

1. Bot A (Adaptive): Paper portfolio is 100% QQQ.
2. Bot B (FearGreed): Paper portfolio is 50% QQQ, 50% CASH.
3. Aggregation:
   • QQQ Target = (1.0 × 0.6) + (0.5 × 0.4) = 0.8 (80%)
   • CASH Target = (0.0 × 0.6) + (0.5 × 0.4) = 0.2 (20%)
4. Final Target: The copier will try to make your live account hold $80,000 of QQQ.

---

🛠 Configuration Reference

Variable	Description
COLLECTIVE2_API_KEY	Your C2 API v4 key. Get it from the C2 API Dashboard.
COLLECTIVE2_SYSTEM_ID	The ID of your C2 strategy.
IB_GATEWAY_HOST	Hostname or IP of IB Gateway (default: 127.0.0.1).
IB_GATEWAY_PORT	API port for IB Gateway (default: 4004).
IB_CLIENT_ID	Unique client ID for the copier (default: 17). Do not use Master Client ID (0).
IB_ACCOUNT_ID	Your Interactive Brokers account ID (e.g., DU1234567 for paper, U1234567 for live).
ETORO_API_KEY	Your eToro Public API Key from the eToro API Portal.
ETORO_USER_KEY	Your eToro User Key (generated in API Portal settings).
ETORO_DEMO	true for demo/paper account, false for live account (default: true).
DARWINEX_USERNAME	Your Darwinex DXtrade username.
DARWINEX_PASSWORD	Your Darwinex DXtrade master password.
DARWINEX_ACCOUNT_ID	Optional: Specific Darwinex account ID to use.
DARWINEX_DEMO	true for demo/paper account, false for live account (default: true).
LIVETRADE_BOT_WEIGHTS	JSON: {"botname": 0.6, "otherbot": 0.4}. Weights are normalized to 1.0.
LIVETRADE_MIN_ORDER_USD	Skip trades smaller than this amount (default: $50).
LIVETRADE_DRY_RUN	true: Logs orders without sending them. Always start here.
LIVETRADE_STRICT_MAPPING	true: Aborts the sync if any target ticker is unmapped, instead of silently skipping it.
LIVETRADE_PORTFOLIO_FRACTION	Fraction of broker equity to allocate to copy-trading. Default 1.0 (use the full account); 0.5 would mirror the bot portfolios into half the account and leave the rest as cash. Range: (0, 1].

Enabling the Copiers in Helm

Each broker is its own CronJob, gated by a separate flag in helm/tradingbots/values.yaml. All default to false — opt in independently:

liveTrade:
  enabled: true     # Collective2 copier
  # ...
liveTradeIB:
  enabled: true     # Interactive Brokers copier
  # ...
liveTradeEToro:
  enabled: true     # eToro copier
  # ...
liveTradeDarwinex:
  enabled: true     # Darwinex copier
  # ...

You can run any combination of brokers (Collective2, IBKR, eToro, Darwinex), or none.

---

🏦 Interactive Brokers (IBKR)

The framework supports Interactive Brokers via IB Gateway (or TWS).

1. Requirements

• IB Gateway running and configured for API access.
• Paper Account strongly recommended for initial testing.
• Paper Port: Usually 4002 (standard) or 4004 (often used in local setups).

2. Configuration

Set these environment variables:

Variable	Description	Default
IB_GATEWAY_HOST	Hostname of IB Gateway.	127.0.0.1
IB_GATEWAY_PORT	API Port.	4004
IB_CLIENT_ID	Unique ID for this connection.	17
IB_ACCOUNT_ID	Your IB account ID (e.g., DU1234567).	Required
LIVETRADE_DRY_RUN	Paper-safety: defaults to true.	true

3. Usage

uv run python tradingbot/livetrade_interactive_brokers.py

4. Ticker Discovery for IB

uv run python -m tradingbot.livetrade.discover_symbols --broker ib

---

🐂 eToro

The framework supports eToro via their Public REST API.

1. Requirements

• eToro Public API Key & User Key. Obtain them from the eToro API Portal.
• Paper Account (Virtual Portfolio) is strongly recommended. Set ETORO_DEMO=true.

2. Configuration

Set these environment variables:

Variable	Description	Default
ETORO_API_KEY	Your eToro API Key.	Required
ETORO_USER_KEY	Your eToro User Key.	Required
ETORO_DEMO	true for paper trading, false for live.	true
LIVETRADE_DRY_RUN	Safety: defaults to true.	true

3. Order Model (USD Amount)

eToro orders are placed using USD Amount (notional) for BUY orders, which allows for fractional shares automatically. For SELL orders, the framework closes existing positions by their positionId.

4. Ticker Mapping

eToro uses numeric Instrument IDs. The framework automatically resolves these via the eToro search API during the mapping phase.

5. Usage

uv run python tradingbot/livetrade_etoro.py

---

📈 Darwinex (DXtrade)

The framework supports Darwinex via the DXtrade REST API (/dxsca-web).

1. Requirements

• Darwinex DXtrade Account (Username + Master Password).
• Demo Account strongly recommended for initial testing.

2. Configuration

Set these environment variables:

Variable	Description	Default
DARWINEX_USERNAME	Your DXtrade username.	Required
DARWINEX_PASSWORD	Your DXtrade master password.	Required
DARWINEX_DEMO	true for demo/paper trading, false for live.	true
DARWINEX_ACCOUNT_ID	Optional: defaults to the first account found.	None

3. Symbol Mapping (CFDs)

Darwinex is a CFD broker. Common equity tickers like QQQ are often mapped to QQQ.US. The framework uses a two-step resolution:

1. Check symbol_mappings.json for manual overrides.
2. Search the Darwinex catalog for the ticker (and ticker + .US).

4. Native Quotes

DXtrade REST API does not provide a simple "last price" endpoint (it is WebSocket only). For v1, the framework falls back to yfinance for real-time price lookups to calculate equity and order sizing.

5. Usage

uv run python tradingbot/livetrade_darwinex.py

---

🔍 Ticker Mapping (Discovery)

Broker symbols (e.g., EURUSD) rarely match yfinance tickers (EURUSD=X) exactly.

1. Run Discovery

Find unmapped tickers in your bot portfolios:

uv run python -m tradingbot.livetrade.discover_symbols

2. Review and Approve

Open symbol_map.review.json. For each ticker, manually add the selected_symbol and selected_type keys:

"BTC-USD": {
  "candidates": [...],
  "selected_symbol": "BTCUSD",  // YOU ADD THIS
  "selected_type": "crypto"     // YOU ADD THIS
}

3. Apply

uv run python -m tradingbot.livetrade.discover_symbols --apply

---

🛡 Going Live Checklist

1. Dry Run: Run for at least 3-5 days with LIVETRADE_DRY_RUN=true.
2. Verify Equity: Confirm the "Broker total equity" logged matches your broker dashboard.
3. Strict Mode: Set LIVETRADE_STRICT_MAPPING=true.
4. Start Small: Use one bot with a low weight (e.g., 0.1) first.
5. Manual Check: After the first live sync, verify the orders appear in your broker's "Open Orders" or "Positions" tab.

---

🏗 Deployment (Kubernetes)

Deploy the copier as a CronJob that runs after your trading bots finish.

apiVersion: batch/v1
kind: CronJob
metadata:
  name: livetrade-copier
spec:
  schedule: "5 21 * * 1-5" # 9:05 PM UTC (Post-market)
  jobTemplate:
    spec:
      template:
        spec:
          containers:
          - name: copier
            image: your-repo/tradingbot:latest
            command: ["python", "tradingbot/livetrade_collective2.py"]
            envFrom:
            - secretRef:
                name: tradingbot-secrets

---

🔌 Adding a New Broker

To support a new broker, implement the LiveBroker interface in tradingbot/livetrade/broker.py:

1. get_positions(): Return Dict[symbol, qty].
2. get_total_equity(): Return float (Cash + Market Value).
3. place_order(symbol, qty, side, type): Execute the trade.
4. get_latest_price(symbol): Return current price for a broker symbol.
5. map_symbol(yf_symbol): Convert yf ticker to broker ticker.
6. search_symbol(query): Helper for ticker discovery.

Reference tradingbot/livetrade/collective2.py for a complete example.

---

❓ Troubleshooting

Issue	Root Cause	Solution
401/403 Error	Invalid API Key	Ensure you are using a v4 key from the C2 dashboard.
Empty "Results"	Wrong System ID	Verify COLLECTIVE2_SYSTEM_ID matches your strategy URL.
"Order Failed" Log	Broker Rejection	Check the log line for ErrorCode; usually due to buying power or invalid symbol.
All targets unmapped	Typo or Empty Bot	Verify bot names in LIVETRADE_BOT_WEIGHTS match the DB exactly.
Quantity 0 warning	Min Order Filter	Increase a specific bot's weight or decrease LIVETRADE_MIN_ORDER_USD.

---

🚫 When NOT to Use

• Before you have at least 1 month of paper trading history.
• With a System ID that you do not own/manage.
• If you require sub-second execution (this is a scheduled copier, not a HFT engine).