trading-bot

A crypto trading framework built risk-first: strategies propose, the risk manager disposes.

Most hobby trading bots are a strategy with an exchange client bolted on. This one inverts that. The strategy layer only emits signals; a dedicated risk manager sits between signals and execution and can veto or resize any order before it reaches a broker. Everything defaults to paper trading with conservative limits.

core/risk/manager.py: "Every rule here exists because 'the strategy said so' is not a safe reason to trade."

Architecture

core/
  data/           Market data feeds (CCXT crypto feed, pluggable base)
  strategy/       Signal generation — MA crossover, ML signal, common base
  risk/           Position sizing, exposure caps, stop-loss, kill switches
  execution/      Broker abstraction — paper broker and live CCXT broker
  backtest/       Event-driven backtest engine with fees and slippage
  portfolio.py    Position and equity tracking
  config.py       Typed config loading
config/
  settings.yaml   Safe-by-default configuration
scripts/
  run_backtest.py Backtest entry point

Risk controls

Configured in config/settings.yaml, enforced in core/risk/manager.py:

Control	Default	Purpose
max_position_pct	25%	Cap on equity in any single position
max_portfolio_exposure_pct	75%	Cap on total deployed equity
stop_loss_pct	5%	Per-position stop
daily_loss_limit_pct	3%	Halt trading for the day after this drawdown
max_orders_per_hour	10	Order-rate limiter / runaway-loop guard

The risk manager returns a RiskDecision — approved, an adjusted qty, and a human-readable reason — so every veto and resize is explainable after the fact.

Backtesting

The backtest engine models the costs that make most naive backtests lie:

• Fees — 0.1% per trade, typical spot taker fee
• Slippage — 0.05% assumed on market fills
• Configurable initial capital, symbol set, timeframe, and history depth

python -m scripts.run_backtest

Strategies

• ma_crossover — fast/slow moving average crossover (20/50 by default). Fully implemented; serves as the reference strategy and backtest sanity check.
• ml_signal — scaffolded, not yet trained. Designed around gradient-boosted trees (XGBoost) over engineered technical features, predicting next-bar return direction with a confidence score. GBTs over deep learning deliberately: tabular financial features at this data scale favour robustness and auditability, and walk-forward validation is simpler to reason about. The interface is defined so the risk manager, executor, and backtester need no changes when the trained model drops in.

Setup

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env    # exchange API keys — only needed for live mode
python -m scripts.run_backtest

Default config is binance spot, BTC/USDT and ETH/USDT, 1h bars, paper trading. Live execution via core/execution/ccxt_broker.py requires explicit opt-in and real API keys.

Stack

Python · CCXT · pandas · NumPy · scikit-learn · XGBoost · PyYAML · Streamlit + Plotly (dashboard) · pytest

Status

Framework and backtesting path are working. The ML strategy is a defined interface awaiting a trained model, and the Streamlit dashboard is not yet built out. Paper trading only — nothing here is investment advice.

License

MIT