TradeBot 🤖📈

AI-assisted daily trading system with a mandatory human approval gate. Analyzes your watchlist every morning, sends trade proposals to Telegram with one-tap ✅/❌ buttons, and fires approved orders via the Alpaca API — complete with stop-loss and take-profit on every position.

⚠️ Paper trade first. This bot defaults to Alpaca's paper trading environment. Validate signal quality for 30–60 days before enabling live trading.

---

Architecture

Market data (Alpaca/Polygon)
        ↓
Technical analysis engine
  RSI · MACD · Bollinger Bands · MA cross · Volume
        ↓
Optional LLM context (Claude API)
        ↓
Telegram digest → YOU approve/reject (⏰ 30-min window)
        ↓
Bracket order: entry + stop-loss + take-profit
        ↓
EOD P&L report → Telegram

---

Quick start

1. Clone and install

git clone https://github.com/shehanmakani/tradebot.git
cd tradebot
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -r requirements.txt

2. Configure credentials

cp .env.example .env
# Edit .env with your keys (see setup guide below)

3. Get your Telegram chat ID

python get_chat_id.py
# Follow the prompt — add the ID to .env as TELEGRAM_CHAT_ID

4. Run a paper test (no orders placed)

python main.py --paper-test

5. Run the full pipeline (paper mode)

python main.py

---

Setup guide

Alpaca Markets

1. Sign up at alpaca.markets
2. Go to Paper Trading → API Keys → Generate
3. Add ALPACA_API_KEY and ALPACA_SECRET_KEY to .env
4. Keep LIVE_TRADING=false until you're satisfied with paper results

Telegram Bot

1. Open Telegram → search @BotFather → send /newbot
2. Follow prompts → copy the token → add as TELEGRAM_BOT_TOKEN in .env
3. Send your bot any message (e.g. "hello")
4. Run python get_chat_id.py → copy the ID → add as TELEGRAM_CHAT_ID

LLM Context (optional)

Enriches proposals with Claude-generated narrative context.

1. Get an Anthropic API key
2. Add as ANTHROPIC_API_KEY in .env
3. Set USE_LLM_CONTEXT=true

---

Scheduling with cron

Add this to your crontab (crontab -e) to run automatically:

# Analysis + approval digest at 8:30am ET (adjust for your timezone)
30 8 * * 1-5 /path/to/.venv/bin/python /path/to/tradebot/main.py >> /path/to/tradebot/logs/cron.log 2>&1

# EOD P&L report at 4:15pm ET
15 16 * * 1-5 /path/to/.venv/bin/python /path/to/tradebot/main.py --eod-report >> /path/to/tradebot/logs/cron.log 2>&1

---

Configuration

Edit config.py to customize:

Setting	Default	Description
WATCHLIST	12 tickers	Tickers to analyze daily
MAX_POSITION_PCT	5%	Max portfolio allocation per trade
MAX_DAILY_TRADES	5	Hard cap on orders per day
STOP_LOSS_PCT	4%	Stop-loss on every order
TAKE_PROFIT_PCT	8%	Take-profit on every order
DAILY_LOSS_LIMIT_PCT	2%	Halt trading if portfolio drops this much in a day
MIN_SCORE_TO_TRADE	60	Minimum signal score (0–100) to propose a trade
APPROVAL_DEADLINE_MIN	30	Minutes before unapproved proposals expire

---

Signal scoring

Each ticker receives a composite score (0–100) across four signal families:

Signal	Max pts	Bullish condition	Bearish condition
RSI	30	RSI < 30 (oversold)	RSI > 70 (overbought)
MACD	25	Histogram crosses above 0	Histogram crosses below 0
Bollinger Bands	20	Price near lower band	Price near upper band
Moving averages	15	MA20 > MA50	MA20 < MA50
Volume confirmation	10	Spike in direction of signal	—

Only proposals scoring ≥ MIN_SCORE_TO_TRADE (default 60) are sent to Telegram.

---

Running tests

python -m pytest tests/ -v

Tests run entirely on synthetic data — no API keys required.

---

Risk disclosure

This software is for educational and research purposes. Automated trading involves substantial risk of loss. Past signal performance does not guarantee future results. Always paper trade before using real capital. The authors are not financial advisors.

---

Project structure

tradebot/
├── main.py                   # Pipeline orchestrator
├── config.py                 # All settings
├── requirements.txt
├── get_chat_id.py            # One-time Telegram setup helper
├── .env.example              # Copy to .env and fill in keys
├── core/
│   ├── analyzer.py           # Technical analysis + scoring
│   ├── broker.py             # Alpaca API integration
│   └── llm_context.py        # Optional Claude enrichment
├── approvals/
│   └── telegram_gate.py      # Telegram approval bot
├── data/
│   └── trade_log.py          # JSON trade history
├── logs/
│   └── trades/               # Daily proposal + execution logs
└── tests/
    └── test_analyzer.py      # Unit tests (no API keys needed)

---

Built by @shehanmakani