Master Trade Copier

V1 foundation for a deterministic Telegram -> Signal Intelligence -> Risk Logic -> MT5 execution system.

The project starts with GOLD/XAUUSD only and keeps live trading decisions rule-based. Telegram and MT5 integrations are adapter layers; the parser, validator, entry logic, risk sizing, state machine, and database schema can be tested without connecting to Telegram or a broker.

Current Scope

• Parse Telegram GOLD/XAUUSD BUY/SELL signals.
• Normalize entry zones, stop loss, and multiple take profits.
• Reject low-confidence or malformed signals.
• Apply price-chasing protection, waiting-entry logic, spread checks, and effective RR checks.
• Calculate risk-based lot size from account equity and broker symbol properties.
• Track duplicate signals by deterministic fingerprint.
• Provide PostgreSQL schema and rule-engine specification.
• Include optional adapter stubs for Telethon and MetaTrader 5.

Quick Start

Run the local review dashboard (simulation mode):

python3 -m trade_copier.web_server

Then open http://127.0.0.1:8787.

Run the pure-Python demo:

python3 scripts/run_signal_demo.py

Run the tests:

python3 -m unittest discover -s tests

Install optional runtime pieces only where they are needed:

python3 -m pip install -e ".[api,telegram,mt5,dev]"

MetaTrader 5 automation should be tested on a demo account first. Automated execution can lose money quickly if parsing, symbol mapping, volume calculation, broker precision, or order-state reconciliation is wrong.

Windows Trading Hub

For 24/7 operation, run Telegram and MetaTrader 5 on an always-on Windows PC. The setup and account-connection flow is documented in docs/windows_hub_setup.md. The dashboard is delivered as an installable web app for Windows, macOS, and Android; the Windows hub remains the only machine responsible for broker execution.

Project Layout

trade_copier/
  api.py                 Optional FastAPI surface
  commands.py            Telegram management command parser
  config.py              Rule and risk defaults
  dedupe.py              Duplicate-signal guard
  entry_engine.py        Logical entry, wait, and skip decisions
  models.py              Normalized signal and trade decision models
  mt5_adapter.py         Optional MT5 gateway
  orchestrator.py        Parse -> validate -> decide -> size pipeline
  parser.py              Telegram signal parser
  risk.py                Lot sizing and account guards
  state.py               Signal lifecycle transitions
  symbols.py             GOLD/XAUUSD alias and broker mapping
  telegram_listener.py   Optional Telethon listener
  validation.py          Signal validation rules
  web_server.py          Dependency-free local dashboard server
db/schema.sql            PostgreSQL schema
docs/rule_engine_spec.md V1 deterministic rule specification
tests/                   Pure unit tests
web/                     Branded local dashboard interface