Architecture

🦉 AthenaAI is an AI-powered ensemble machine-learning trading bot for PocketOption, built on BinaryOptionsToolsV2 → Get it on GitLab
💬 Need help? Join the Chipa Discord · ⚡ Go no-code with ChipaEditor

AthenaAI (src/bot.py, class AITradingBot) is an asyncio application built around three concurrent loops that share in-memory state: a candle stream feeding a deque of recent candles, a decision loop that turns candles into trades, and a result checker that resolves trades and feeds outcomes back into the models.

Component diagram

                       ┌───────────────────────────────┐
                       │   PocketOption (websocket)    │
                       │   via BinaryOptionsToolsV2    │
                       └──────┬───────────────▲────────┘
              candle stream   │               │  buy/sell, check_win
                              ▼               │
┌─────────────────────────────────────────────┴──────────────────────┐
│                        AITradingBot (src/bot.py)                   │
│                                                                    │
│  _candle_stream ──► candles: deque(maxlen=lookback)                │
│                            │                                       │
│  _trade_loop:              ▼                                       │
│   ┌ FeatureEngine ──── feature vector (core + experimental)        │
│   ├ RegimeDetector ─── trending / ranging / volatile               │
│   ├ EnsemblePredictor─ direction + confidence                      │
│   │    (SGD, PA, NB  +  GBM, RF, optional MLP)                     │
│   ├ Signal gates ───── conf band, alignment, confirmations, …      │
│   ├ AdaptiveStrategy ─ blocked regimes/hours, conf adj, cooldown   │
│   ├ MoneyManager ───── Kelly stake, daily loss limit               │
│   └ ExpirySelector ─── best expiry from expiry_options             │
│                            │  buy()/sell()                        │
│  _result_checker:          ▼                                       │
│   check_win ──► PerformanceTracker, MoneyManager, TradeJournal,    │
│                 AdaptiveStrategy, ExpirySelector, FeatureLab,      │
│                 EnsemblePredictor (online learning)                │
└────────────────────────────────────────────────────────────────────┘
        │                        │                       │
        ▼                        ▼                       ▼
  athena_brain.pkl     athena_brain_expiry.pkl    trade_journal.db
  (ensemble state)     (expiry win stats)         (SQLite journal)

Key modules:

Startup sequence

bot.start() runs, in order:

1. Banner — prints asset, timeframe, expiry options, model roster, confidence band, trading hours, feature counts.
2. Brain load or retrain — if PO_RETRAIN=1, the saved brain file is deleted and retraining is forced. Otherwise _load_brain() tries brain_path; on success it also loads <brain>_expiry.pkl (expiry stats) and logs ✅ Loaded saved brain — skipping dataset training!.
3. Fallback if no brain:
   • _reload_from_journal() — replays completed trades from trade_journal.db into the ensemble, restores win/loss stats, and feeds the adaptive strategy.
   • _load_dataset(dataset_path) — if PO_DATASET is set, pre-trains on the CSV with a 70/30 walk-forward split, then saves the brain.
4. Connect — creates PocketOptionAsync(ssid=...), waits 3 seconds for the websocket handshake, logs Connected! Balance: $X.XX.
5. Warmup candles — fetches history via get_candles(asset, timeframe, offset_seconds). The offset is seconds of history (effective_warmup × timeframe), and warmup is floored at 60 candles because features need at least 50 (SMA50).
6. Run — asyncio.gather(_candle_stream(), _trade_loop(), _result_checker()).

The three concurrent loops

1. _candle_stream — market data in

Prefers subscribe_symbol_time_aligned(asset, timedelta(seconds=timeframe)), which delivers completed candles at interval boundaries, so features are always computed on closed candles rather than noisy in-progress ticks. If the installed BinaryOptionsToolsV2 version lacks it, it falls back to subscribe_symbol(asset, timeframe). Each incoming candle is appended to the deque if its timestamp is newer; a candle with the same timestamp replaces the last entry (same candle updating). On stream error the loop logs Candle stream error: ... and sets _running = False, stopping the whole bot.

2. _trade_loop — decisions

Ticks every poll_interval (2 s default) and walks a sequence of gates; the first failing gate skips the tick. A ⏸ <reason> diagnostic is logged at most every 30 seconds. Gate order:

1. Warmup (< max(warmup_candles, 60) candles)
2. Max concurrent trades (max_concurrent_trades, default 1)
3. Minimum wait between trades (min_wait_between_trades, default 60 s)
4. Daily loss limit (MoneyManager.can_trade())
5. Consecutive-loss cooldown window
6. Trading-hours filter (UTC hour must be in trading_hours)
7. Adaptive extra cooldown (cold-streak penalty from AdaptiveStrategy)
8. Feature computation (skip if None)
9. Volatile-regime skip (if skip_volatile_regime, off by default)
10. Confidence band: min_confidence ≤ conf ≤ max_confidence
11. Low-range candle skip (candle range < 0.00005, ~0.5 pips on EURUSD)
12. Indicator alignment (2-of-3 of RSI / MACD histogram / SMA cross must agree)
13. Signal confirmation (signal_confirmations consecutive candles agreeing; default 1)
14. 5-minute multi-timeframe trend confirmation (SMA5 vs SMA20 on every-5th-candle series)
15. Adaptive strategy gate (blocked regimes/hours, direction preference, adjusted threshold)

If everything passes: MoneyManager.compute_stake() sizes the trade, ExpirySelector.select() picks the expiry, the bot logs ▶ TRADE ... and calls client.buy() or client.sell(). The trade is stored in pending_trades, journaled immediately, and its feature vector kept on the record for later learning. Gate details: Signal gates.

3. _result_checker — outcomes and learning

Every 3 seconds it scans pending_trades:

• A trade is only checked once elapsed ≥ expiry + 2 seconds — the 2 s pads for broker settlement.
• check_win(trade_id) responses are parsed defensively: dict (result/status keys) or string, lowercased; if the parsed value isn’t win/loss/draw, it falls back to substring matching ("win", "loss"/"lose", "draw") anywhere in the raw response, else retries next cycle.
• On a resolved trade: profit is computed (win = stake × 0.85, loss = -stake, draw = 0), then fed to the performance tracker, money manager, journal, adaptive strategy, and expiry selector, and a ✅ WIN / ❌ LOSS / ➖ DRAW line is logged.
• Online learning: the stored features are labeled (win → predicted direction was correct; loss → the opposite direction), added to the ensemble, partial_fit runs every retrain_every (10) new results, and batch models (GBM/RF/MLP) retrain on a sliding window of the last 500 samples once at least 200 are buffered (every 100 thereafter).
• Every 10 completed trades: a performance snapshot row is written and the brain autosaved.
• Stale abandonment: if check_win keeps erroring and the trade is older than expiry × 5, it is dropped with Abandoning stale trade <id> after timeout (never resolved, never learned from).

Data flow summary

candles → FeatureEngine.compute → nan_to_num → RegimeDetector
       → EnsemblePredictor.predict → (direction, confidence)
       → gates → MoneyManager.compute_stake → ExpirySelector.select
       → buy/sell → pending_trades + journal
       → check_win → profit → perf/money/journal/adaptive/expiry stats
       → label = win ? direction : 1 - direction → ensemble.add_sample
       → partial_fit every 10 results; batch retrain on last 500 samples

File artifacts

Full details and how to reset each: Persistence.

Shutdown

Ctrl+C raises KeyboardInterrupt in main.py, which calls bot.stop(): sets _running = False, saves the brain and expiry stats, and logs Bot stopped. Final stats: ....

See also

• Live trading — operating the bot and reading its logs
• Ensemble — how predictions are made
• Persistence — everything on disk

💬 Questions about running AthenaAI? Ask in the #trading-bots channel on the Chipa Discord — and if you’d rather design strategies without touching Python, try ChipaEditor.