Signal Trader

A Python automation tool that monitors email accounts for trading signals and automatically executes trades on various trading platforms. Perfect for algorithmic traders who receive signals via email from services like TradingView.

⚠️ WARNING: USE AT YOUR OWN RISK ⚠️

AUTOMATED TRADING INVOLVES SIGNIFICANT FINANCIAL RISKS

• Test thoroughly with mock brokers before connecting to real trading accounts
• Validate all configurations carefully, especially trading parameters
• Start with small trade volumes when transitioning to real trading
• Verify signal parsing works correctly for your specific email formats
• Financial losses may occur - never invest money you cannot afford to lose
• You are responsible for all trading decisions made using this software

See the documentation for more detailed warnings and instructions.

🚀 Features

• Email Integration: Securely connects to email providers (Gmail, etc.) to retrieve trading signals
• Signal Processing: Parses emails to extract trading signals with customizable formats
• Multi-Platform Support: Execute trades on different platforms:
  • MetaTrader 5
  • Bybit
  • Extensible architecture for adding more platforms
• Configurable Trading: Set default parameters for different assets (stop loss, take profit, etc.)
• Scheduling: Periodically check for new signals at configurable intervals
• Robust Logging: Comprehensive logging of all operations and trades
• Service Mode: Run as a background service on Linux/macOS
• Docker Support: Easy deployment with Docker and docker-compose
• CLI Interface: Command-line tools for manual operations and monitoring
• Modular Design: Easily extend with new signal formats or trading platforms

📋 Requirements

• Python 3.9 or higher
• For MetaTrader 5 integration: Windows OS or Wine on Linux/macOS
• Email account with IMAP access

🔧 Installation

Standard Installation

1. Clone the repository:

   git clone https://github.com/meatulbisht/signal-trader.git
   cd signal-trader

2. Create a virtual environment and activate it:

   python -m venv venv
   
   # On Windows
   venv\Scripts\activate
   
   # On macOS/Linux
   source venv/bin/activate

3. Install the package and dependencies:

   # Basic installation
   pip install -e .
   
   # With MetaTrader 5 support
   pip install -e ".[mt5]"
   
   # With all optional dependencies
   pip install -e ".[all]"
   
   # For development
   pip install -e ".[dev]"

4. Create your configuration:

   cp config.example.yaml config.yaml

5. Edit config.yaml with your email credentials and trading preferences.

Docker Installation

1. Build and start the container:

   docker-compose up -d

2. Check the logs:

   docker-compose logs -f

🔍 Configuration

The config.yaml file controls all aspects of Signal Trader:

# Email Configuration
email:
  server: "imap.gmail.com"
  port: 993
  username: "your-email@gmail.com"
  password: "your-app-password"  # Use app passwords for Gmail
  use_ssl: true

# Trading Platform Configuration
mt5:
  server: "your-broker-server"
  login: 12345678
  password: "your-mt5-password"
  path: "/path/to/terminal64.exe"

# General Settings
settings:
  check_interval: 60  # Check for new emails every 60 seconds
  time_window: 2      # Only check emails from the last 2 minutes

See config.example.yaml for a complete configuration example with all options.

📊 Usage

Command Line Interface

Signal Trader provides a command-line interface for various operations:

# Start the scheduler to periodically check for signals
python -m signal_trader start

# Manually check for new emails and process signals
python -m signal_trader check_emails

# Run as a service (Linux/macOS)
python -m signal_trader.run_service --action start

# Run a simulation with mock components
python -m signal_trader.run_simulation

# Run with real email checking but mock trading
python -m signal_trader.run_real_check --broker mock

As a Python Package

You can also use Signal Trader as a library in your own Python code:

from signal_trader.email_client.client import EmailClient
from signal_trader.signal_processor.parser import SignalParser
from signal_trader.trading.broker_factory import get_broker
from signal_trader.trading.trade_executor import TradeExecutor

# Initialize components
email_client = EmailClient(config.email.dict())
parser = SignalParser()
broker = get_broker({'type': 'mt5'})
executor = TradeExecutor(broker)

# Process emails
emails = email_client.fetch_unread_emails()
for email_msg in emails:
    signal = parser.parse_email(email_msg)
    if signal:
        success = executor.process_signal(signal)

🏗️ Architecture

Signal Trader follows a modular architecture with these main components:

1. Email Client: Connects to email servers and retrieves messages
2. Signal Processor: Parses emails to extract trading signals
3. Trading Module: Executes trades on various platforms
4. Scheduler: Coordinates the periodic checking of emails
5. Configuration: Manages settings and credentials
6. Logging: Records all operations and trades

🧪 Testing

Run the test suite with pytest:

# Run all tests
pytest

# Run with coverage report
pytest --cov=signal_trader

# Run specific test modules
pytest tests/test_email_client.py

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgements

• MetaTrader5 for the trading platform API
• TradingView for signal generation capabilities