Crypto Collab - Windows Trading System

A professional, Windows-first cryptocurrency trading system with comprehensive safety features and AI guidance.

🎯 Purpose

Crypto Collab is a single-user, Windows-only trading application designed to run mostly hands-off while preventing losses through comprehensive safety mechanisms. The system uses AI guidance to choose strategies and markets, executes trades automatically when safety guardrails pass, and provides a professional cockpit GUI for monitoring.

✨ Key Features

🛡️ Safety First

• Hard blocks for suicidal configurations (NO OVERRIDES)
• Daily drawdown kill switch with customizable limits
• Pre-trade checklist with comprehensive validation
• Order idempotency to prevent duplicate trades
• Orphan cleanup for abandoned orders
• Adaptive risk defaults based on market conditions

🤖 AI-Powered Trading

• Strategy selection guided by AI analysis
• Market pair recommendations with risk assessment
• Automatic execution when guardrails pass
• Confidence-based filtering for trade quality

💻 Professional GUI

• System tray integration with Windows notifications
• Web-based cockpit with real-time updates
• Named pipe API for secure service communication
• Emergency kill switch accessible from tray and GUI

📊 Comprehensive Monitoring

• Real-time portfolio tracking with P&L analysis
• Position monitoring with unrealized gains/losses
• System health metrics and performance monitoring
• Alert system via Telegram, email, and Windows notifications

🔧 Enterprise Features

• Audit trail logging for compliance and debugging
• Support bundle generation for troubleshooting
• Backtesting engine for strategy validation
• Paper trading mode with live parity checking

🏗️ System Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Tray App      │    │  Web Cockpit    │    │  Named Pipe     │
│                 │    │                 │    │  API Server     │
└─────────┬───────┘    └─────────┬───────┘    └─────────┬───────┘
          │                      │                      │
          └──────────────────────┼──────────────────────┘
                                 │
                    ┌─────────────┴───────────────┐
                    │     Core Trading Service    │
                    │                             │
                    │  ┌─────────────────────────┐│
                    │  │   Safety Validator      ││
                    │  │   Kill Switch Manager   ││
                    │  │   Order Manager         ││
                    │  │   Risk Engine          ││
                    │  │   Alert System         ││
                    │  └─────────────────────────┘│
                    └─────────────┬───────────────┘
                                  │
                    ┌─────────────┴───────────────┐
                    │     Exchange APIs           │
                    │  (Binance, Coinbase, etc.)  │
                    └─────────────────────────────┘

📋 Requirements

System Requirements

• Operating System: Windows 10 or Windows 11
• Python: 3.11 or higher
• Memory: 4GB RAM minimum, 8GB recommended
• Storage: 2GB free space minimum
• Network: Stable internet connection for exchange APIs

Exchange Support

• ✅ Binance (Primary)
• ✅ Coinbase Pro
• ✅ Kraken
• ✅ KuCoin
• ✅ Bybit

🚀 Quick Start

1. Download and Setup

1. Clone or download this repository to your desired location
2. Run the setup script as Administrator:

   setup.bat

   This will:
   • Create a Python virtual environment
   • Install all required dependencies
   • Initialize the database
   • Create necessary directories

2. Configuration

1. Edit the configuration file: config/default.toml

2. Add your exchange API credentials:

   [exchange]
   name = "binance"
   api_key = "your_api_key_here"
   api_secret = "your_api_secret_here"
   testnet = true  # KEEP TRUE FOR SAFETY INITIALLY

3. Configure alerts (optional):

   [global.alert_routes]
   email = "your.email@example.com"
   telegram_bot_token = "your_bot_token"
   telegram_chat_id = "your_chat_id"

4. Adjust risk settings:

   [global]
   position_cap_pct = 2.0      # Max 2% per position
   daily_drawdown_pct = 5.0    # Kill switch at 5% daily loss

3. First Run

1. Start the core service:

   launch_service.bat

2. Launch the tray application:

   launch_tray.bat

3. Open the web cockpit:

   launch_cockpit.bat

   Then navigate to: http://localhost:8000

4. Safety Check

The system will perform comprehensive startup checks:

• ✅ Configuration validation
• ✅ Exchange connectivity
• ✅ Safety guardrail verification
• ✅ Database initialization
• ✅ Disk space and permissions

⚠️ IMPORTANT: Do not bypass any safety checks. If checks fail, resolve the issues before proceeding.

🔧 Configuration Guide

Core Settings

Global Risk Management

[global]
max_spread_pct = 0.35           # Max bid-ask spread (0.35%)
position_cap_pct = 2.0          # Max position size (2% of equity)
portfolio_cap_pct = 25.0        # Max total exposure (25%)
daily_drawdown_pct = 5.0        # Daily kill switch (5% loss)
safe_mode = true                # Enable conservative defaults

Exchange Configuration

[exchange]
name = "binance"                # Exchange name
testnet = true                  # Use testnet (RECOMMENDED)
rate_limit_per_min = 1200       # API rate limit
enable_withdrawals = false      # Disable withdrawals (SECURITY)

AI Planner Settings

[ai_planner]
mode = "recommend_then_auto"    # AI operation mode
whitelist = ["BTCUSDT", "ETHUSDT"]  # Allowed pairs only
budget_cap_pct = 15.0          # Max AI control (15% of portfolio)
confidence_threshold = 0.7      # Min confidence for auto-execution

Strategy Configuration

[strategy]
name = "ma_crossover"           # Strategy to use
allows_high_vol = false         # Handle high volatility

[strategy.stop_loss]
atr_multiplier = 2.0            # ATR-based stop distance
max_loss_pct = 3.0              # Max loss per position (3%)

[strategy.cooldowns]
loss_streak = 3                 # Consecutive losses before cooldown
cooldown_minutes = 60           # Cooldown duration

Safety & Risk Management

[safety]
enable_kill_switch = true       # Enable emergency stop

[safety.pre_trade_checks]
min_liquidity_usd = 1000000     # Min 24h volume ($1M)
max_volatility_pct = 20.0       # Max volatility unless allowed

[safety.profit_protection]
enabled = true                  # Lock profits
lock_threshold_pct = 10.0       # Start protection at 10% gain
protection_pct = 50.0           # Protect 50% of profits

🎮 Usage Guide

Daily Operation

1. Morning Routine:

   • Check system health in tray app
   • Review overnight alerts
   • Verify exchange connectivity
   • Check portfolio status

2. Starting Trading:

   • Right-click tray icon → "Start Trading"
   • Or use web cockpit "▶ Start Trading" button
   • Monitor initial trades carefully

3. Monitoring:

   • Keep tray app running for notifications
   • Check web cockpit periodically
   • Review alerts and system health

4. Evening Routine:

   • Review daily P&L
   • Check for any alerts or issues
   • Optionally stop trading for overnight

Emergency Procedures

Kill Switch Activation

Method 1 - Tray App:

1. Right-click tray icon
2. Click "🚨 KILL SWITCH"
3. Confirm activation

Method 2 - Web Cockpit:

1. Open http://localhost:8000
2. Click "🚨 EMERGENCY KILL SWITCH"
3. Confirm activation

What Kill Switch Does:

• ❌ Stops all trading immediately
• 🔄 Cancels all open orders
• 📧 Sends emergency alerts
• 🛡️ Activates safe mode

System Recovery

1. Identify the issue from logs and alerts
2. Fix the root cause (config, connectivity, etc.)
3. Reset kill switch via tray app or cockpit
4. Restart trading when safe to do so

Web Cockpit Features

The web cockpit (http://localhost:8000) provides:

Dashboard Overview

• 💰 Portfolio Balance with daily change
• 📈 P&L Today with percentage
• 📊 Active Positions count and exposure
• ⚡ System Status with health indicators

Position Management

• Real-time position tracking
• Entry price vs current price
• Unrealized P&L for each position
• Position side (BUY/SELL) indicators

System Health

• Service uptime
• API latency
• Memory and CPU usage
• Database size
• Log file count

Trading Controls

• Start/Stop trading
• Toggle safe mode
• Emergency kill switch
• Force data refresh

Alert Center

• Recent system alerts
• Alert levels (Info, Warning, Critical)
• Timestamps and details
• Alert acknowledgment

🔍 Troubleshooting

Common Issues

Service Won't Start

❌ Problem: Service fails startup checks
✅ Solution:
1. Check config/default.toml for errors
2. Verify API credentials are correct
3. Ensure exchange is reachable
4. Check logs in logs/ directory

API Connection Failed

❌ Problem: Cannot connect to exchange
✅ Solution:
1. Verify API keys and permissions
2. Check if testnet is enabled/disabled correctly
3. Ensure firewall allows connections
4. Check exchange status page

Tray App Not Responding

❌ Problem: System tray icon not working
✅ Solution:
1. Ensure core service is running first
2. Check named pipe permissions
3. Restart tray app: launch_tray.bat
4. Check Windows notification settings

Web Cockpit 404 Error

❌ Problem: http://localhost:8000 not accessible
✅ Solution:
1. Start cockpit server: launch_cockpit.bat
2. Check if port 8000 is available
3. Verify no firewall blocking
4. Try different port in cockpit_server.py

Trading Not Starting

❌ Problem: Start trading button doesn't work
✅ Solution:
1. Check if all safety checks pass
2. Review startup self-check results
3. Verify configuration is not suicidal
4. Check kill switch is not triggered

Log Files

Logs are stored in the logs/ directory:

• service_YYYYMMDD.log - Core service logs
• tray_app.log - Tray application logs
• cockpit.log - Web cockpit logs
• alerts.log - Alert system logs

Debug Mode

To enable debug logging:

1. Edit config/default.toml
2. Set log_level = "DEBUG"
3. Restart all services

Getting Help

1. Check this README for common solutions
2. Review log files in logs/ directory
3. Generate support bundle:
   • Use tray app → "📋 Support Bundle"
   • Or run: python -m core.support_bundle
4. Contact support with support bundle attached

🔒 Security Considerations

API Key Security

• ✅ Use testnet initially for all testing
• ✅ Create trading-only keys (no withdrawal permissions)
• ✅ IP whitelist your keys if exchange supports it
• ❌ Never share API keys or commit them to version control

System Security

• 🔐 Run as standard user (not Administrator) after setup
• 🔐 Keep Windows updated for security patches
• 🔐 Use antivirus software and keep definitions current
• 🔐 Regular backups of configuration and database

Network Security

• 🌐 Use secure network (not public WiFi) for trading
• 🌐 Enable Windows Firewall
• 🌐 Monitor network traffic for unusual activity
• 🌐 Use VPN if required for your region

Trading Security

• 📊 Start with small amounts to test system
• 📊 Monitor positions closely during initial runs
• 📊 Keep kill switch accessible at all times
• 📊 Review all trades for unexpected behavior

📚 Advanced Features

Backtesting

Run historical strategy tests:

python -m backtesting.runner --strategy ma_crossover --start-date 2024-01-01 --end-date 2024-06-01

Results saved to backtesting/results/

Paper Trading

Enable paper trading mode:

[exchange]
testnet = true
paper_trading = true

This simulates real trading without actual orders.

Custom Strategies

1. Create new strategy in strategies/ directory
2. Inherit from strategies.base.BaseStrategy
3. Implement required methods
4. Add to configuration:

   [strategy]
   name = "your_custom_strategy"

Plugin System

Add custom functionality:

1. Create plugin directory: plugins/my_plugin/
2. Add plugin.json with metadata
3. Implement strategy.py with required interface
4. Configure in config/default.toml

Alert Customization

Add custom alert handlers:

from core.alert_system import AlertSystem, AlertLevel

# Register custom handler
def my_alert_handler(alert):
    # Your custom logic here
    pass

alert_system.register_custom_handler('my_handler', my_alert_handler)

📈 Performance Optimization

System Resources

• Memory Usage: Typically 100-200MB
• CPU Usage: <5% during normal operation
• Disk Usage: ~50MB base + logs and data
• Network: Minimal - only API calls

Optimization Tips

1. Close unnecessary applications during trading hours
2. Use SSD storage for better database performance
3. Stable internet connection (consider backup connection)
4. Monitor system resources via Task Manager
5. Regular cleanup of old log files

Scaling Considerations

• Single exchange: Up to 50 concurrent positions
• Multiple exchanges: Configure separate instances
• High-frequency strategies: Consider dedicated hardware
• Large portfolios: Increase position and risk limits gradually

🆘 Support and Maintenance

Regular Maintenance

• Weekly: Review log files and clear old ones
• Monthly: Update dependencies if needed
• Quarterly: Full system backup and testing
• Annually: Review and update API keys

Backup Strategy

Important files to backup:

• config/default.toml - Your configuration
• data/cc.db - Trading database
• logs/ - Recent log files
• Custom strategies and plugins

Updates and Upgrades

1. Stop all services before updating
2. Backup current installation
3. Test updates in development environment
4. Apply updates during non-trading hours
5. Verify all systems after update

Emergency Contacts

• Kill Switch: Always accessible via tray app
• Exchange Support: Keep exchange support contacts ready
• System Administrator: For critical system issues

📄 License and Disclaimer

IMPORTANT DISCLAIMER: This software is for educational and research purposes. Trading cryptocurrencies involves significant risk and can result in financial losses. The authors and contributors are not responsible for any trading losses or system failures. Use at your own risk.

License: Proprietary - All rights reserved.

🏆 Acknowledgments

Special thanks to:

• Security researchers who identified potential vulnerabilities
• Beta testers who provided valuable feedback
• Exchange API teams for stable trading interfaces
• Open source community for foundational libraries

---

Remember:

• 🛡️ Safety first - Never bypass safety checks
• 📚 Start small - Test with minimal amounts initially
• 🔍 Monitor closely - Keep watch on system and trades
• 🚨 Keep kill switch ready - Always accessible for emergencies

Happy Trading! 🚀