Algo-Scanner (pyTrade)

A lightweight desktop scanner that monitors crypto/forex pairs, applies a candlestick-based strategy (pandas_ta) and notifies you via GUI, sound and Telegram.

✅ Features

• Real-time OHLCV fetching (ccxt/Exchange for crypto, optional MetaTrader5 for forex)
• Candle-close signal detection (bull / bear) via strategy.py
• Desktop GUI with chart preview, logs and per-pair timers (app.py)
• Telegram alerts and local audio alerts (buy.mp3 / sell.mp3)
• Persistent settings & pairs in trading_config.json

---

Quick start (Windows)

1. Create a virtual environment and activate it (PowerShell):

python -m venv .venv
.\.venv\Scripts\Activate.ps1

2. Install dependencies:

pip install ccxt pandas pandas_ta customtkinter pygame python-dotenv requests
# Optional (Forex/MT5):
# pip install MetaTrader5

3. Run the app:

python app.py

---

Requirements

• Python 3.8+
• Packages: ccxt, pandas, pandas_ta, customtkinter, pygame, python-dotenv, requests
• Optional: MetaTrader5 for local Forex data

Tip: You can also add the packages above to a requirements.txt and run pip install -r requirements.txt.

---

Configuration

• Main persisted configuration: trading_config.json (pairs + UI/settings).
• Environment variables (optional) — create a .env file in project root to enable Telegram:

TELEGRAM_BOT_TOKEN=your_bot_token
TELEGRAM_CHAT_ID=your_chat_id
TELEGRAM_PROXY=http://127.0.0.1:12334   # optional

• Sound files: buy.mp3 / sell.mp3 (replace via Settings in the GUI).
• To pre-load scanner pairs/settings, edit trading_config.json before starting the app.

---

How to use

• Start the app (python app.py).
• Add a pair and timeframe in the left sidebar and click ADD TO SCANNER.
• Open SETTINGS to adjust strategy parameters, proxy, audio, or Telegram credentials.
• Signals appear in the pair log and are mirrored to the System log; audio/Telegram are sent based on settings.

GUI Quick actions

• Test Telegram: Settings → Telegram Settings → "Send Test Message".
• Test sound: Settings → Audio → "Test Buy" / "Test Sell".

---

Project layout (key files)

• app.py — main GUI, worker threads, ticker collector, UI and persistence.
• data_manager.py — fetches OHLCV (ccxt for crypto, optional MT5 for forex), rate-limit & circuit-breaker logic.
• strategy.py — signal logic (returns "bull" or "bear" plus price).
• trading_config.json — saved pairs and settings loaded at startup.
• error_traces.log — persisted tracebacks and debug details.
• buy.mp3, sell.mp3 — alert audio files.
• TODO.MD — outstanding items and known issues.

---

Strategy & tunables

• Strategy implementation: strategy.analyze_strategy(df, shadow_ratio, sma_dist_multiplier, min_bars)
• Change defaults in GUI → Settings or edit trading_config.json.
• Important settings: shadow_ratio, sma_dist_multiplier, min_bars, ticker_interval, proxy_url.

---

Logs & troubleshooting

• UI logs: System / per-pair logs inside the app.
• Persistent traces: error_traces.log (useful for exceptions and stack traces).
• Common issues:
  • "Audio device not found": app will continue but audio alerts disabled.
  • Network / exchange errors: DataManager applies retries and a circuit-breaker — check System logs.
  • MT5/Forex: requires MetaTrader5 package and a local MT5 terminal connected.
  • PowerShell activation errors: use Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass or run activate in CMD.

---

Known TODO / limitations

(see TODO.MD)

• Autotrade is not implemented — scanner only notifies (no order execution).
• Some network reliability issues reported; consider enabling proxy or reviewing error_traces.log.
• UX: add trend indicator next to pair name (planned).

---

Development & contribution

• Suggested workflow:
  1. Create a branch, add tests (where appropriate), open a PR.
  2. Keep GUI logic in app.py, fetch logic in data_manager.py, and strategy code in strategy.py.
• If you change strategy logic, keep parameter defaults in both GUI Settings and trading_config.json.

Please open issues or PRs for feature requests or bug fixes.

---

Security & disclaimer

This tool is provided for research and alerting only — it does NOT place trades. Use at your own risk; verify strategy results on paper trading before any live deployment.

---