📉 ApexVoid Trading Bot 🤖

A self-hosted Telegram bot for posting and tracking XAUUSD (Gold) trading signals by hand, with optional AI chart analysis. It runs as a single long-polling process — no inbound webhook server, no public endpoint, no TLS required. 🚀

┌────────────┐   DM    ┌──────────────────────────┐        ┌────────────┐
│  You (DM)  │ ──────▶ │  Telegram bot (aiogram)  │ ─────▶ │  Telegram  │
│  + charts  │         │  ├─ 📝 manual parse      │        │  channel   │
└────────────┘         │  ├─ 🔄 lifecycle track   │        └────────────┘
                       │  ├─ 🧮 pips calculator    │
                       │  └─ 👁️ Claude vision      │
                       └────────────┬─────────────┘
                                    ▼
                          ┌──────────────────────┐
                          │ 💾 SQLite            │
                          │ ├─ manual_signals    │
                          │ └─ pips_log          │
                          └──────────────────────┘

The bot talks to Telegram over outbound long-polling only, meaning it requires zero open ports, no domain names, and no reverse proxy to operate securely. 🔒

---

✨ Features

📡 Manual Signal Posting (DM interface)

• Insta-Post Signals ⚡ — DM gold sell entry zone (4100-4105) / sl 4110 / tp 95/90/80 and the bot will instantly post a beautifully formatted signal to the channel.
• TP Shorthand 🎯 — Just write the last 2 digits (35 → 3835). You can list any number of TPs!
• Scalp Metadata ⚡ — Add / scalp or / scalp nhanh to mark a fast scalp internally for review/stats without exposing a channel tag.
• Lifecycle Tracking 🔄 — Every signal is tracked. DM /trade_active to see open positions, /trade_close XAU #3 +80 to log a result, /trade_uncclose XAU #3 to restore a mistaken close, or /trade_cancel XAU #3 to drop it.
• Cancel by Reply 🗑️ — Simply reply cancel directly to a channel signal post; the bot removes the original and cleans up your reply.
• Owner-Exclusive 👑 — Set TELEGRAM_OWNER_ID to strictly lock all DM commands to you.

📣 VIP + Public Broadcast

• SIGNAL_VIP_CHANNEL_ID is the private control channel; bare lifecycle commands are accepted only there.
• SIGNAL_PUBLIC_CHANNEL_ID receives broadcast-only signal posts and updates without internal #id values.
• SIGNAL_PUBLIC_SHOW_PIPS=true shows per-signal results publicly; set it to false for event-only wording. Aggregate stats always stay in owner DM.
• Signals publish to both channels by default. Add / vip to an entry to keep that signal and all later updates VIP-only.
• The bot must be an administrator with post/edit permissions in both channels.
• A restart-safe Sunday performance recap is delivered to VIP only. Configure it with WEEKLY_REPORT_ENABLED, WEEKLY_REPORT_DOW, and WEEKLY_REPORT_HOUR; public never receives aggregate performance.

🗓 Economic Calendar

• The daily ForexFactory brief includes only configured high-impact USD, gold, and oil events. The bot stays silent when none are scheduled.
• Calendar briefs are broadcast to both VIP and public channels.
• Upcoming events can tag or block a new signal through the local event guard.

🧮 Pips Calculator

• DM calculate gold pips today or this week for a win/loss pips summary drawn from the local pips_log (populated automatically whenever you close a result).
• Auto-edit Pips ✏️ — Post +80 pips or -30 pips in the channel and the bot replaces it with a clean formatted result (even works on photos!).

🧠 AI Chart Analysis

• DM one or more chart screenshots and the bot will run a structured Smart Money Concepts (SMC) analysis via Claude Vision, automatically drafting the setup to the channel.
• Multi-Timeframe Aware ⏱️ — Send several charts; it uses higher TFs for directional bias and lower TFs for entry precision.

🤖 ApexVoid Algo (demo)

• Scanner detectors own complete strategy matching. With AUTO_TRADE_STRATEGY_BRIDGE_ENABLED=true, the strongest completed M5 match is sent to ApexVoid Algo as typed data without parsing Telegram text or asking a private regime/M1 gate to confirm it again.
• It builds a 60-bar M1 auction box only after repeated reactions at both edges, at least 82% of closes remain inside, and close-path efficiency shows consolidation rather than trend. This remains a separate private strategy, not a market regime. When private strategies overlap, the higher-confluence match wins; regime classification is telemetry rather than a veto.
• A box entry closes the full position at +50 pips, or +70 pips when at least 75 pips of clean room remain to the opposite edge. Box mode does not scale in or use planned zone-fill orders.
• Two accepted M1 closes, or one accepted M5 close, outside the box retire that box and stop new entries from it. A used edge must first travel through the box midpoint before that same side can fire again.
• The lane still fails closed on stale quotes, excessive spread, entry drift, guarded news, and an existing XAU position. There is no daily trade cap; a validated box may keep cycling until its breakout is confirmed.
• /auto_status exposes the selected source, scanner strategy/direction, latest private-strategy state, and selected box for diagnostics. The typed routing design is documented in docs/algo-strategy-match-routing.md.

---

🛠️ Tech Stack

Layer	Choice
Runtime	Python 3.12 🐍
Telegram Bot	aiogram 3 (long-polling) 🤖
AI Analysis	Anthropic Claude (Vision) 👁️
Persistence	SQLite (aiosqlite) 🗄️
Packaging	Docker + Compose v2 🐳

---

📚 Documentation

Dive into the docs for full details on configuring and operating the bot:

• 📖 Bot Commands — Manual posting, lifecycle (active/close/cancel), pips calculator, auto-edit, env setup.
• 🏗️ Architecture — Process model, message flow, database schema, design decisions.
• 🚀 Deployment Guide — From a fresh host to a running bot.
• ⚙️ Operations — Monitoring, backups, log rotation, updates, troubleshooting.
• 🔒 Security — Threat model, secret management, hardening.
• 📊 Redis Bar Contract — Closed OHLC window keys shared by the cTrader feed and scanners.
• 📝 Changelog — Notable behavior, configuration, and deployment changes.

---

🚀 Quick Start

git clone <this-repo> apexvoid-trading-bot
cd apexvoid-trading-bot

# Setup Environment
cp .env.example .env
# Edit .env: TELEGRAM_BOT_TOKEN, SIGNAL_VIP_CHANNEL_ID,
#            SIGNAL_PUBLIC_CHANNEL_ID, SIGNAL_PUBLIC_SHOW_PIPS,
#            TELEGRAM_OWNER_ID,
#            ANTHROPIC_API_KEY (chart analysis)

# Deploy
docker compose up -d --build
docker compose logs -f bot

Expected startup lines:

bot: DB ready at /data/signals.db
bot: Starting Telegram polling

Then, just DM your bot: active should reply with 📋 No open signals. 🎉

---

📁 Repository Layout

apexvoid-trading-bot/
├── docker-compose.yml        🐳 bot + postgres + redis + cTrader feed
├── .env.example              🔑 env template
├── README.md                 📖 this file
├── docs/                     📚 detailed documentation
├── ctrader-engine/           📊 .NET: cTrader Open API feed + auto-trade execution
└── telegram-bot/             🤖 the Telegram bot application
    ├── Dockerfile
    ├── requirements.txt
    ├── scripts/               🧰 one-off/manual utility scripts
    └── app/
        ├── main.py            🏁 entrypoint: init DB, start long-polling
        ├── core/               ⚙️ settings (pydantic-settings) and symbol config
        ├── persistence/        🗄️ PostgreSQL store + Redis watcher state
        ├── bot/                💬 aiogram: client, wiring, keyboards, handlers/
        ├── signals/            📡 manual-signal lifecycle: parsing, broadcast, watcher, reports
        ├── analysis/           📈 price-action primitives, detectors, scanner, market map
        └── autotrade/          🤖 independent auto-scalp gate, scale context, worker, delivery

---

📄 License

Private project. Not licensed for redistribution. ⛔