AI Trader

A Python-based cryptocurrency paper-trading project with two strategy modes:

• Rule-based trading driven by RSI, Stochastic RSI, and z-scored volume.
• AI-based trading powered by a Deep Q-Network (DQN) policy.

The bot fetches Kraken market candles, scores each new candle, simulates BUY/SELL actions against a local portfolio file, logs results to CSV, and can send Discord notifications.

---

What this project does

• Runs on a fixed candle interval (configured in .env).
• Pulls recent OHLCV data from Kraken.
• Computes indicators (RSI, Stoch RSI, volume normalization, and Bollinger features for AI mode).
• Makes a trading decision (rule logic or trained AI model).
• Simulates trades in portfolio.json (paper trading only).
• Writes logs to data/dataLogs/data_log.csv.

This repo is designed for experimentation and learning. It is not financial advice and should not be used as-is for live trading with real funds.

---

Project structure

AI-Trader/
├── main.py                    # Entry point: choose AI mode or rule-based mode
├── config.py                   # Validated runtime and training settings
├── baseDirectory/
│   ├── aiBased.py             # AI startup + live inference loop
│   └── ruleBased.py           # Rule-based scoring + trade loop
├── dashboard/                  # Local monitoring and training dashboard
├── AI/
│   ├── brain.py               # DQN model + replay memory utilities
│   ├── experiment.py          # Reproducibility + model metadata helpers
│   ├── datasets.py            # Chronological train/validation/test preparation
│   ├── evaluate.py            # Backtests, baselines, metrics, and reports
│   ├── features.py            # Shared versioned feature + scaling pipeline
│   ├── train.py               # DQN training flow
│   └── TradingEnv.py          # RL environment for training
├── indicators/
│   ├── RSIIndicators.py       # RSI + Stochastic RSI
│   ├── volume.py              # z-score volume feature
│   └── bb.py                  # Bollinger-band features
├── data/
│   ├── getData.py             # Kraken candle fetcher
│   ├── auditLog.py             # Structured AI paper-trading audit records
│   ├── paperTrade.py          # Portfolio simulation (buy/sell/balance)
│   ├── writeOut.py            # General logging
│   └── writeOutTrades.py      # Trade event logging
├── AImodels/                  # Saved `.pth` models
├── data/dataLogs/             # CSV logs
├── tests/                     # Deterministic environment and DQN tests
└── portfolio.json             # Paper portfolio state

---

Requirements

• Python 3.11+
• pip
• Optional: CUDA-enabled PyTorch for faster training

Install dependencies:

pip install -r requirements.txt

---

Environment configuration

Copy .env.example to .env in the project root, then adjust values for the market and experiment you want to run.

# Kraken config. Use the public API root, not the /OHLC endpoint.
KRAKEN_PUBLIC=https://api.kraken.com/0/public
PAIR=BTCUSD
INTERVAL=300
CANDLE=5

# Indicator + sizing
RSIPERIOD=14
HOWMANYYOUWANT=0.01
INITIALPAPERMONEY=1000
TAKER_FEE=0.004
PAPER_SLIPPAGE_BPS=5
MAX_STALENESS_SECONDS=600
MAX_CONSECUTIVE_ERRORS=3
MAX_DRAWDOWN_PCT=20
PORTFOLIO_PATH=portfolio.json

# Optional net-return risk limits. Blank disables each one.
RISK_STOP_LOSS_PCT=
RISK_TAKE_PROFIT_PCT=

# Rule-based thresholds
BUYTHRESHOLD=1.5
SELLTHRESHOLD=-1.5
NOTIFBUYTHRESHOLD=1.0
NOTIFSELLTHRESHOLD=-1.0

# Training experiment
TRAIN_DATASET=data/historical_data/XBTCAD_5.csv
TRAIN_MODEL_NAME=trading_model
TRAIN_EPISODES=2715
TRAIN_EPISODE_WINDOW=6000
TRAIN_SEED=42

# fixed, manual, or generated model-selected risk
TRAIN_RISK_MODE=fixed
TRAIN_RISK_PRESETS=0.01:0.02,0.02:0.04,0.03:0.06
TRAIN_MIN_STOP_LOSS_PCT=0.005
TRAIN_MAX_STOP_LOSS_PCT=0.02
TRAIN_MIN_TAKE_PROFIT_PCT=0.01
TRAIN_MAX_TAKE_PROFIT_PCT=0.05
TRAIN_RISK_PERCENTAGE_STEP=0.005
TRAIN_MIN_REWARD_TO_RISK_RATIO=2.0
TRAIN_MAX_RISK_PRESET_COUNT=30

Variable notes

• CANDLE is in minutes (e.g. 5).
• INTERVAL is in seconds (e.g. 300) and should match CANDLE.
• HOWMANYYOUWANT is position size per trade.
• INITIALPAPERMONEY seeds the simulated balance.
• TAKER_FEE is applied by both the training environment and paper trading.
• PAPER_SLIPPAGE_BPS applies adverse simulated execution slippage to training, evaluation, and paper trading.
• MAX_STALENESS_SECONDS rejects old Kraken candles, while MAX_CONSECUTIVE_ERRORS stops a live loop after repeated failures.
• MAX_DRAWDOWN_PCT liquidates an open paper position and blocks new buys after the account reaches the configured drawdown.
• RISK_STOP_LOSS_PCT and RISK_TAKE_PROFIT_PCT are decimal net-return targets after entry and exit fees. For example, use 0.02 for a 2% stop loss and 0.04 for a 4% take profit. Blank values disable the limits.
• MARKET_RETRY_ATTEMPTS, MARKET_RETRY_BACKOFF_SECONDS, and MARKET_REQUEST_TIMEOUT_SECONDS bound retries for transient Kraken failures.
• TRAIN_DATASET, TRAIN_EPISODES, TRAIN_EPISODE_WINDOW, and the remaining TRAIN_* values in .env.example control a DQN experiment without source edits.
• TRAIN_RISK_MODE=fixed keeps the three legacy actions and Phase 8 global limits. manual uses TRAIN_RISK_PRESETS; generated builds finite SL/TP combinations from the configured ranges and step.
• Blank generated minimums and TRAIN_MIN_REWARD_TO_RISK_RATIO disable those filters. Finite maximums and a positive step are still required, and the preset-count guard prevents an accidentally huge DQN output layer.
• The network action count is derived automatically as hold + one action per buy preset + sell. Do not set TRAIN_ACTION_SIZE.

---

How to run

From the repo root:

py main.py

You will be prompted to choose:

1. AI Based Trading bot
2. Rule Based Trading Bot

AI mode

• Can train a new model or resume training.
• Loads a selected model from AImodels/.
• Uses the model to choose HOLD, BUY, or SELL each candle.

Rule-based mode

• Computes a weighted score from RSI / Stoch RSI / zVolume.
• Buys above BUYTHRESHOLD, sells below SELLTHRESHOLD.

---

Training notes (AI)

Training is launched from the AI startup prompt. Each named run writes five files in AImodels/:

• <name>.pth: final inference model.
• <name>.checkpoint.pth: resumable training state.
• <name>.metadata.json: seed, dataset range, installed package versions, and training parameters.
• <name>.evaluation.json: machine-readable validation, final-test, baseline, trade, and equity results.
• <name>.evaluation.txt: a compact readable results summary.

If you want to retrain from scratch:

1. Start python main.py
2. Choose option 1 (AI)
3. Enter y for training
4. Provide a model name
5. Choose resume n

DQN environment behavior

• The DQN sees 12 values: normalized OHLC, RSI, Stochastic RSI, z-scored volume, three Bollinger features, current position, and normalized balance.
• Fixed mode uses 0 = HOLD, 1 = BUY, and 2 = SELL. Manual and generated modes use 0 = HOLD, actions 1..N = BUY with one exact SL/TP preset, and action N+1 = SELL.
• The training environment can hold either no asset or exactly one configured lot. Invalid buys and sells receive a small penalty but still advance one candle.
• Each reward is the fee-aware log return in total portfolio value over the next candle. Any open position is automatically sold at the final candle so an episode always ends in cash.
• Preset selection receives no artificial bonus. The DQN learns from the same net portfolio return after fees, and the selected percentages stay fixed for that position.
• Long histories use seeded random 6,000-candle windows by default, so episodes cover different market regimes without loading every candle into each episode.

Historical data

The default dataset is Kraken's five-minute XBTCAD_5.csv. Seven-column Kraken OHLCVT exports and twelve-column Binance kline exports are detected automatically. Missing Kraken no-trade intervals are regularized as flat, zero-volume candles before chronological splitting so the feature cadence remains exactly five minutes.

Keep the live PAIR consistent with the quote currency used by the training file before running a trained model. For example, XBTCAD_5.csv is Bitcoin priced in Canadian dollars, while XBTCHF_5.csv would be Bitcoin priced in Swiss francs.

DQN feature contract

• Training and live inference use the same feature builder and the same fixed feature order.
• The ten market features are standardized using means and scales fitted on training data only. Position and balance remain explicit ratios.
• The feature schema, lookbacks, missing-data policy, column order, and fitted scaler are stored in each model's metadata and checkpoint.
• Live inference loads the saved scaler and rejects missing or incompatible metadata before making a decision.
• Models created before this feature contract are considered legacy and must be retrained before they can be selected for AI paper trading.

DQN training stability

• Training uses separate online and target networks so the network being optimized does not also generate its own immediate targets.
• Optimization starts only after the replay buffer reaches its warm-up size and uses Huber loss with gradient clipping.
• Exploration, replay size, target-update cadence, batch size, checkpoint cadence, and the main optimizer settings are configurable through trainDQN.
• Checkpoints include both networks, optimizer state, replay memory, episode and step counters, epsilon, and random-generator states so training can resume from an episode boundary.
• Python, NumPy, and PyTorch are seeded from TRAIN_SEED before training starts. Reusing the same data, settings, seed, machine, and package versions should produce comparable results.

Honest evaluation

• Candles are split chronologically into training, validation, and final-test periods. The default split is 70% / 15% / 15% and can be changed with the EVAL_* settings in .env.example.
• Feature normalization is fitted only on the training period. Validation chooses the best saved checkpoint; the final test period is not read by optimization or model selection.
• Reports include return, realized PnL, drawdown, completed trades, win rate, exposure, annualized Sharpe ratio, the same-lot buy-and-hold baseline, and a no-trade baseline.
• The walk-forward section evaluates the frozen selected policy on sequential, non-overlapping windows within the final test period.

Recreate the report for any compatible saved model with:

py -m AI.evaluate --model AImodels/trading_model.pth

Paper-trading safety

AI paper trading only starts a model when its weights, feature schema, saved normalization, validation-selected checkpoint, final-test result, pair, candle length, position size, starting balance, fee, and slippage settings all agree with the current configuration. An incomplete, legacy, or resumable checkpoint is rejected before it can make a decision.

Stop-loss and take-profit exits use completed candle close prices. When a configured level is reached, the runtime sells before requesting a DQN action and records either stop_loss_triggered or take_profit_triggered. New buys persist their fee-aware levels in portfolio.json; preset-mode buys also persist the model-selected preset and percentages. An open trade keeps its entry-time settings even if .env changes later.

Every new model stores its complete ordered action schema. Paper trading and checkpoint resume reject changed preset order, ranges, steps, filters, or action counts before loading network outputs. Pre-Phase-9 three-action models remain compatible only in matching fixed mode; manual and generated modes require training a new model.

Each candle attempt appends one row to data/dataLogs/ai_audit_log.csv. The log is append-only and contains the UTC timestamp, model and feature version, candle time and price, action index, complete Q-value vector, hold/best-buy/sell Q summaries, selected preset, confidence margin, balance, quantity, position, cumulative and per-trade PnL, fee, and a reason such as policy_hold, already_holding, insufficient_cash, or fresh_market_data_unavailable.

Temporary market-data failures retry with exponential backoff. If all attempts fail, or if the fresh response does not contain enough valid history for the saved feature pipeline, that candle is recorded as skipped and the bot waits for the next one. It never makes a decision from an older response.

Local dashboard

Run the FastAPI dashboard from the project root:

py -m dashboard.app

Then open http://127.0.0.1:8000. It binds to localhost by default and has no authentication, so keep it local. The page can start a new training run, resume a checkpoint, stop training, and display its live output. It does not call market-data or trade functions and never places an order.

The overview automatically handles a first run with no data. Once artifacts exist, it reads these contracts:

• portfolio.json: balance, quantity, realized_pnl, order count, entry accounting, active stop/take prices, and the selected risk preset.
• data/dataLogs/ai_audit_log.csv: timestamped decisions, skips, risk exits, complete Q-values, selected presets, confidence, balances, quantities, fees, active limits, and reasons.
• AImodels/<name>.metadata.json: active model identity, feature schema, exact action schema, runtime parameters, selected checkpoint, and compact results.
• AImodels/<name>.evaluation.json: final-test metrics, baseline comparison, equity curve, trade markers, and results grouped by risk preset.

Run the automated tests with:

py -m unittest discover -s tests -v

---

Logging and outputs

• Portfolio state persists in portfolio.json.
• Candle-by-candle logs are written to data/dataLogs/data_log.csv.
• AI decision and skip audit records are written to data/dataLogs/ai_audit_log.csv.
• Trade-specific events are written via writeOutTrades.py.
• Discord notifications are sent when DISCORD_WEBHOOK is configured in .env.

---

Known limitations

• This is a paper-trading simulator, not an exchange execution engine.
• Risk exits are simulated from completed candle closes, not exchange-native orders or intrabar price ordering.
• There is no daily-loss or multi-asset exposure guard yet; the configured maximum-drawdown guard is process-local paper-trading protection, not an exchange order.

---

Roadmap ideas

• Add strategy sensitivity and stress testing across fees and position sizes.
• Add unit tests for the remaining standalone indicator implementations.
• Add multi-seed experiment comparison and rolling retraining.

---