Skip to content

About

This is a free and open-source cryptocurrency trading bot written in Python.

Topics

Resources

Stars

6 stars

Watchers

2 watching

Forks

Latest commit

Β 

History

542 Commits

Folders and files

NameName
Last commit message
Last commit date
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

MCT Trading Bot

CI linting: pylint codecov pre-commit License: PolyForm Noncommercial Docker pull Discord chat

MCT (stands for ML-Crypto-Trading) is a high-performance trading engine that features a Dynamic Expression Engine allowing users to define position sizing and risk management logic using familiar, spreadsheet-like functions.

Tip

Financial Logic Without the Code. If you can write an Excel-style formula, you can define trading logic in MCT. The engine provides access to real-time market data, balances, and technical indicators (RSI, EMA, SMA) directly in your configuration.

Caveat Utilitor! For educational and research purposes only.


Community

Join our Discord community to discuss strategies, report issues, and collaborate with other traders:

Discord Banner


Table of Contents


Quick Start

The bot can be run using Make / standard Python or Docker.

Prerequisites

  • Python 3.11+ (Python 3.12 recommended)
  • PostgreSQL: A running instance (local Docker, native service, or remote like Supabase, Neon, AWS RDS).
  • Operating System: macOS, Linux, or Windows (PowerShell, WSL, or Git Bash).

Interactive CLI Setup Wizard (Recommended)

Launch the guided interactive terminal installer to configure your environment, provision the PostgreSQL database, setup exchange & LLM credentials, install dependencies, and run database migrations:

macOS / Linux:

./install.sh
# Or via Make
make install-interactive

Windows (PowerShell):

.\install.ps1

Automated / CI/CD Mode: Run unattended with defaults or specific profiles:

./install.sh --non-interactive --profile=quickstart
# Simulate without writing files
./install.sh --dry-run

πŸ“– For traditional step-by-step setup scripts, manual .env configuration, database migration commands, and automated CI profiles, see the full Installation & Setup Guide.


Core Features

  • Dynamic Expression Engine: Define custom position sizing formulas and strategy triggers directly in YAML using spreadsheet-style syntax with access to real-time indicators (rsi, sma, ema), account equity, and market state.
  • BFT Consensus Engine: Byzantine Fault Tolerant multi-strategy decision engine supporting flexible voting models, including single-strategy execution, independent OR triggers, and strict multi-strategy consensus.
  • High-Fidelity Backtesting: Multi-asset historical simulation featuring independent virtual clocks, realistic execution frictions (configurable latency, tick slippage, fee rates), and deterministic tick replay.
  • Strategy Promotion Pipeline: Guarded verification pipeline that evaluates proposed configuration adjustments against historical simulations, checks for execution drift, and enforces quantitative safety criteria before live deployment.
  • Autonomous Activity Monitoring: Background starvation watchdog continuously tracks per-asset market data, evaluations, signals, and executions, proactively flagging trading inactivity without manual intervention.
  • AI Agent System: LangGraph-powered conversational assistant with specialized subgraphs for configuration tuning, on-demand backtesting, performance analytics, and human-in-the-loop approvals.
  • Configuration Version Control (VCS): Git-like content-addressable history tracking for runtime configurations, providing cryptographic audit trails, branch management, and instant rollbacks.
  • Runtime Observability & Telemetry: Built-in collectors for system resources, WebSocket connection health, order lifecycle latencies, execution attribution, and live log streaming.

For motivation, system architecture, and deep-dive conceptual guides, see Introduction & Features and Core Concepts.


Architecture

MCT is built with a modular, decoupled architecture separating execution loops, trading logic, AI agent automation, and transport APIs:

flowchart TD
    subgraph Root["Application & Composition Root"]
        ENGINE["Trading Engine<br/>β€’ Schedulers (Live / Sim / Backtest)<br/>β€’ Dynamic Expression Engine<br/>β€’ BFT Consensus Quorum<br/>β€’ Protection & Drawdown Guards"]
        AGENT["AI Agent & Automation<br/>β€’ LangGraph Chat & Analytics Subgraphs<br/>β€’ Starvation Watchdog Monitoring<br/>β€’ Strategy Promotion Pipeline"]
        SERVER["FastAPI Server & Real-Time Streams<br/>β€’ REST API Endpoints<br/>β€’ SSE Chat (/chat)<br/>β€’ WebSockets (/agent/ws, /logs/ws)"]
    end

    subgraph Managers["Manager Container Layer"]
        MDM["MarketDataManager"]
        ACM["AccountManager"]
        OM["OrderManager"]
        CM["ConsensusManager"]
        PM["ProtectionManager"]
    end

    subgraph Infrastructure["Infrastructure & Persistence"]
        EXCHANGE["Exchanges (Crypto.com, CCXT, Paper)"]
        STORAGE["PostgreSQL / VCS History / Datasets"]
        TELEMETRY["Observability & Metrics Collectors"]
    end

    ENGINE --> Managers
    AGENT --> Managers
    SERVER --> Managers
    Managers --> EXCHANGE
    Managers --> STORAGE
    Managers --> TELEMETRY
Loading

πŸ“– For complete component breakdown, manager containers, and sequence diagrams, see Architecture & Diagrams and Agent Automation & Monitoring.


Dynamic Expressions

MCT features a spreadsheet-style formula engine allowing traders to define algorithmic signals and dynamic order sizing directly in YAML without writing Python code:

# Dynamic position sizing (e.g. risk 2% of equity per trade)
dynamic_quantity: "max(min_qty, (balance * 0.02) / close)"

# Dynamic strategy trigger expression
expression: "rsi(14) < 30 and close > ema(20)"

Expressions evaluate in real time with access to:

  • Market Data: close, high, low, volume, range
  • Account State: balance, equity, pnl (unrealized), position_qty
  • Technical Indicators: rsi(period), sma(period), ema(period), min(...), max(...), avg(...)
  • Signal & Quorum: signal, confidence, vote_ratio

πŸ“– For complete indicator functions, formula syntax, and full configuration schema, see Dynamic Expressions in Core Concepts and the Configuration Guide.


Strategy Promotion Pipeline

The bot features an automated, guarded pipeline for testing and safely promoting strategy adjustments from simulation into live trading:

  • Baseline Performance Comparison: Evaluates candidate configurations against active production benchmarks across return, Sharpe ratio, and max drawdown.
  • Execution Drift Protection: Validates that simulated order fills and execution latencies do not diverge from live journal observations.
  • Safety Policy Gating: Enforces quantitative criteria via PromotionPolicy before allowing human-in-the-loop approval and VCS staging.

πŸ“– For simulation telemetry details, gating thresholds, and API endpoints, see the Strategy Promotion Pipeline Guide.


Makefile Commands Reference

Command Description
make install-interactive Launch guided interactive CLI setup wizard
make setup Bootstrap virtualenv, install dependencies, init .env, and setup git hooks
make venv Create virtual environment and install development dependencies
make install Install production requirements (requirements.txt)
make install-dev Install development requirements (requirements-dev.txt)
make clean Clean virtualenv, pytest cache, coverage files, and python bytecode
make db-setup Check database environment (PostgreSQL / Docker) and readiness
make db-up Start PostgreSQL container via docker compose
make db-down Stop PostgreSQL container
make upgrade Apply pending Alembic migrations (alembic upgrade head)
make downgrade Rollback database migrations to base
make migrate Generate a new Alembic migration revision (make migrate m="my migration")
make format Run pre-commit hooks and code formatters
make lint Run pylint checks
make test Run pytest suite with code coverage
make run-simulated Run paper trading in simulated mode
make run-backtest Run historical backtesting simulation
make run-live Run live trading engine (with integrated API server)
make run-headless Run live trading in headless mode (API server disabled)

Run Modes

MCT supports multiple execution modes for paper trading, historical simulation, live execution, and headless daemon operation:

Mode Purpose Make Target Key CLI Flags
Simulated Trading Real-time market feed with in-memory simulated order execution make run-simulated --simulated=true
Backtesting Historical tick / CSV replay with latency, slippage, and fee modeling make run-backtest --backtest-mode=true --backtest-source=...
Live Trading Real exchange orders + integrated FastAPI & Agent server make run-live --assets-conf=trading-config.yaml
Headless Daemon Production trading engine running without web/API overhead make run-headless --headless=true
API Server Only Interactive chat, metric APIs, and WebSocket streams python main.py --server=true --server=true --api-port=8000

For complete CLI flags, Docker container commands, execution friction parameters (latency, slippage, fees), and audit log replays, see the comprehensive Run Modes Guide.


Documentation

For in-depth guides, architectural blueprints, and API references, browse the documentation in the docs/ directory:


License & Commercial Terms

This project is source-available under the PolyForm Noncommercial License 1.0.0.

  • Free for Personal & Educational Use: You are free to view, download, modify, and run this software for non-commercial purposes, personal trading research, and learning.
  • Commercial Restrictions: Any commercial use, proprietary trading for profit by institutions or funds, hosting MCT as a commercial service/SaaS, or selling software built on MCT requires a separate commercial license from the author.

For commercial licensing inquiries or institutional partnerships, please reach out via Discord or open a private inquiry.

Copyright

Copyright Β© 2026 Toni Akinjiola. All rights reserved.

About

This is a free and open-source cryptocurrency trading bot written in Python.

Topics

Resources

Stars

6 stars

Watchers

2 watching

Forks

Releases

Packages

Used by

Contributors

Languages