ZED — IBKR ETF Mean‑Reversion Bot (Paper)

White Paper (Current State) v0

Date: 2026‑02‑09
Owner: Greg Hickman
System Name: ZED
Mode: Paper trading (IBKR)
Asset Class: US‑listed ETFs (ARCA / USD)
Location: AWS-hosted services + WhatsApp control
Back to top

1) Executive Summary

ZED is a server-hosted automated trading platform built around Interactive Brokers (IBKR) connectivity and a simple quantitative signal engine.

What it does today

  • Runs IB Gateway (paper) with automated login.
  • Connects via the IBKR API using ib_insync.
  • Computes intraday VWAP + z-score deviation signals on a fixed ETF universe.
  • Exposes a WhatsApp control plane (pause/resume/flatten/status/snapshots).
  • Can place paper orders (long-only), subject to risk limits.

Design intent

  • Default-safe: PAUSED unless explicitly resumed.
  • Operational clarity: concise commands + journald logs.
  • Incremental hardening before any live trading.
Back to top

2) System Architecture

2.1 Components

IB Gateway (Paper) + IBC automation

Systemd service: ibgateway-ibc.service

  • Maintains authenticated IBKR paper session
  • IBC handles login and dialog automation
  • Exposes the IB API locally (default port 7497)

ZED Trading Bot

Systemd service: trading-bot.service

  • Python + ib_insync
  • Config: /home/ubuntu/clawd/trading/config/bot.yaml
  • Runtime commands/state: /home/ubuntu/clawd/trading/state/commands.json
  • Logs: journalctl -u trading-bot.service

WhatsApp Control Plane

  • Send commands like zed status, zed resume, zed flatten
  • Commands update bot state; bot loop reacts on next cycle
  • Observability commands read service state and logs

Public Documentation Hosting (This White Paper)

  • Served by nginx on the trading server
  • Primary URL: https://apiqx.com/
  • HTTPS via Let’s Encrypt; HTTP redirects to HTTPS
  • Health check: /health → ok

2.2 Data Flow

  1. IB Gateway maintains authenticated connection to IBKR paper account.
  2. ZED connects to IB Gateway via IB API on 127.0.0.1:7497.
  3. On each cycle (typically ~60s):
    • Fetches 1-minute bars (reqHistoricalData, last 1 day)
    • Computes VWAP and z-score signals
    • If unpaused, may submit orders to align positions with targets
Operational note: IBKR may restrict historical data when another session is connected from a different IP. ZED is designed for a single active IBKR session per account.
Back to top

3) Strategy v0 (As Implemented)

3.1 Universe

Current ETF basket (23 symbols):

SPY, QQQ, IWM, DIA, EEM, EFA, VWO, VGK, FXI, GLD, SLV, USO,
TLT, IEF, LQD, HYG, XLF, XLK, XLE, XLV, XLI, XLY, XLP

3.2 Signal

  • Compute intraday VWAP from 1-minute bars
  • Compute z-score of (last - VWAP) normalized by the day’s dispersion
z = (last - vwap) / std(last - vwap)

3.3 Entry/Exit (Long-only Mean Reversion)

  • Entry (buy): z <= -entry_z (default entry_z = 2.0)
  • Exit (reduce to zero): z >= -exit_z (default exit_z = 0.5)
  • Long-only: no shorts.

3.4 Sizing

Targets are allocated in USD exposure using configuration limits (total gross cap, per-symbol cap, max candidates per side). Allocation is approximately equal across qualifying entries, bounded by caps.

Back to top

4) Risk, Safety & Governance

4.1 Current Safety Controls

Global controls

  • Paused by default; trading requires explicit zed resume
  • Flatten: zed flatten closes positions and pauses

Execution limits

  • Total gross exposure cap
  • Per-symbol exposure cap
  • Minimum trade USD + max order USD chunking
  • Cooldown controls to avoid rapid re-trading

4.2 Paper Trading Only

ZED is explicitly operating in paper mode. Any step toward live trading should be treated as a controlled change with additional testing and governance.

Back to top

5) Observability & WhatsApp Commands

Status/Info

  • zed help
  • zed summary
  • zed status
  • zed snapshot N
  • zed errors N
  • zed trades
  • zed connectivity N

Control

  • zed pause — stop new orders
  • zed resume — allow trading
  • zed flatten — close positions + pause
  • zed restart — restart bot service
Back to top

6) Current Constraints / Known Issues

  1. IBKR API timeouts (intermittent). These can cause skipped cycles; ZED currently tolerates and retries.
  2. Market data subscriptions. Some data may be delayed without real-time subscriptions.
  3. Multi-login restrictions. IBKR may block historical data if the same account is active from another IP.
  4. Execution maturity. v0 execution prioritizes robustness in paper; live readiness needs limit orders, fill tracking, and PnL measurement.
Back to top

7) Roadmap (Next Steps)

Near-term

  • Connectivity hardening (backoff, circuit-breaker, better telemetry)
  • Market-hours awareness to reduce noisy rejects
  • Improve trade reporting (fills, deltas, positions)

Execution hardening

  • Limit orders / price controls
  • Explicit order state machine (submitted/partial/filled/cancelled)
  • Daily loss stop and realized/unrealized PnL tracking

Governance

  • Controlled change process for any move toward live trading
  • Audit log / trade blotter export