Build a safe, signal-driven crypto trading bot.

From clone to first signal in 5 minutes.

Helix ships as a single Python service. Default settings are safe — no real funds are at risk until you explicitly opt in. Always run 7+ days in testnet (or Paper for Kraken) before flipping to live.

# 1. Clone
git clone git@github.com:aminbassam/Auto-Trader.git
cd Auto-Trader

# 2. Configure
cp .env.example .env
$EDITOR .env          # set ACTIVE_EXCHANGE, API keys, Telegram, secret

# 3. Boot (testnet by default)
docker-compose up -d

# 4. Verify
curl http://localhost:8000/health | jq
# → "status": "ok", "active_exchange": "binance", "trading_mode": "testnet"

# 5. Point TradingView at your endpoint
#    Webhook URL:  https://your-vps/webhook
#    Header:       X-Webhook-Secret: $WEBHOOK_SECRET

A signal executor — not a strategy engine.

Indicators live in TradingView (Pine Script v5). Helix's only job is to receive validated signals, gate them through risk, and execute safely. That separation keeps the bot simple and the strategy iterable.

At a glance

Layered, async, and exchange-agnostic.

The factory pattern is the key v1.1 change: the rest of the codebase never references Binance or Kraken directly — only the abstract ExchangeClient interface. Adding Bybit or OKX in v2 means writing one new class.

TradingView Pine Script
   │  (alert fires)
   ▼
HTTPS POST → FastAPI /webhook    [X-Webhook-Secret header]
   │  (Pydantic parse)
   ▼
SignalHandler.dedup(signal_id, 60s window)
   │
   ▼
RiskManager.validate(signal)     [7 pre-trade checks]
   │  (pass)
   ▼
ExchangeFactory.get_client()     [reads ACTIVE_EXCHANGE]
   │
   ▼
ExchangeClient.place_market_order(symbol, side, qty)
ExchangeClient.place_stop_loss()  [OCO or conditional close]
   │
   ▼
SQLite trade log  +  Telegram notify

Abstract interface

Every exchange client implements the same surface. Callers code against the interface — never the concrete class.

class AbstractExchangeClient(ABC):
    @abstractmethod async def connect(): ...
    @abstractmethod async def disconnect(): ...
    @abstractmethod async def get_balance(): ...
    @abstractmethod async def get_ticker(symbol): ...
    @abstractmethod async def place_market_order(symbol, side, qty): ...
    @abstractmethod async def place_oco_order(symbol, side, qty, stop_price): ...
    @abstractmethod async def get_open_positions(): ...
    @abstractmethod async def cancel_order(order_id): ...

class BinanceClient(AbstractExchangeClient):  # spot · OCO · testnet
class KrakenClient(AbstractExchangeClient):   # spot · conditional close · paper

Every signal travels the same path.

Any check can veto. Rejected signals are logged with a reason and a Telegram alert. Successful trades are persisted, summarised, and tracked toward the daily loss budget.

1. Webhook arrives
   POST /webhook with X-Webhook-Secret header. Rate-limited at 10/min.
2. Payload validates
   Pydantic checks signal, symbol, price, signal_id. Malformed → 422.
3. Deduplication
   If the same signal_id was seen in the last 60s, drop silently and log signal_deduplicated.
4. Pre-trade risk checks
   Seven gates run. Failure → reject with reason, Telegram alert, no order placed.
5. Position sizing
   size = (balance × risk_pct) ÷ stop_pct. Below the exchange's min notional → reject.
6. Exchange dispatch
   Factory returns the BinanceClient or KrakenClient based on ACTIVE_EXCHANGE.
7. Market order placed
   With retry × 3 (exponential backoff) on transient network errors.
8. Stop loss attached
   OCO (Binance) or conditional close (Kraken). Exchange-side — survives bot crashes.
9. Persist + notify
   SQLite WAL write, Telegram message, daily P&L counter incremented.

EMA cross with RSI filter, on 5m BTC/USDT.

The default strategy is a clean trend-following signal: EMA(9/21) crossover, gated by an RSI(14) momentum filter. The bot does not compute indicators — they all run in TradingView Pine v5 and arrive pre-computed.

Paste this into your TradingView alert.

TradingView fires alerts at the bot's webhook endpoint. The alert's "Message" field must contain this exact JSON shape, with placeholders for live values.

{
  "signal":    "BUY",
  "symbol":    "BTC/USDT",
  "price":     {{close}},
  "timestamp": {{timenow}},
  "strategy":  "ema_crossover",
  "signal_id": {{strategy.order.id}}
}

Fixed-fraction sizing, market orders, exchange-side stops.

Position size is calculated from account equity and stop-loss distance. Market orders for MVP — limit orders ship in v2. Stop losses live on the exchange, not in the bot, so they survive crashes.

Position sizing

position_size = (account_balance × risk_pct) ÷ stop_loss_distance_pct

# Example with $10,000 equity, 1% risk, 2% stop:
position_size = (10000 × 0.01) ÷ 0.02
              = $5,000 notional
              ≈ 0.078 BTC  at $64,210

# Risk per trade (USD)
$ at risk = account_balance × risk_pct = $100

Single-active per deploy.

Pick one exchange per deployment via the ACTIVE_EXCHANGE env var. The factory loads the right client at boot — only that venue's credentials need to be set. Switching exchanges is one env edit + restart.

Kraken-specific notes

• No public testnet API. The bot ships with a paper mode that simulates fills against live order-book prices. Same risk-management behaviour as live — only the orders are never sent.
• Conditional close orders. Kraken's equivalent to Binance OCO. Attached to the opening order via the close param.
• Stricter rate limits. CCXT's enableRateLimit is on by default, with extra delay between calls.
• XBT vs BTC. Kraken uses XBT for Bitcoin internally; CCXT normalises everything to BTC. You always write BTC/USDT.
• Nonce-based auth. Handled automatically by CCXT.

Seven gates between a signal and an order.

Risk has veto power over every trade. If any check fails, the signal is rejected with a reason and a Telegram alert. The circuit breaker is armed by default and trips on daily loss limit OR max consecutive losses.

Circuit-breaker thresholds

All bot ↔ human communication through Telegram.

Outbound events fire on every state change. Inbound /commands let you query and control the bot from your phone. Only the configured TELEGRAM_CHAT_ID can issue commands — all others are silently ignored.

Three HTTP endpoints.

/webhook is the only externally-facing route. /health is consumed by Docker and uptime monitors. /status is internal.

GET /health response

{
  "status":             "ok",            // ok | degraded | halted
  "uptime_seconds":     184302,
  "active_exchange":    "binance",       // binance | kraken
  "exchange_connected": true,
  "last_signal_time":   "2026-05-15T08:14:32Z",
  "open_positions":     1,
  "daily_pnl_pct":      1.13,
  "trading_mode":       "testnet"        // testnet | live | paper
}

Three SQLite tables. WAL mode.

SQLAlchemy 2.0 async ORM. The schema migrates to Postgres in v2 — same shape, different backend.

trades

signals

daily_stats

All config from .env.

Loaded via pydantic-settings. Never hardcoded. Never logged. .env is gitignored; .env.example is committed as a template.

Required core

Exchange credentials (only the active venue is read)

Optional tuning (defaults applied)

Pinned, async-first Python.

Every exchange call is awaited; every webhook is non-blocking. Dependencies are pinned in requirements.txt.

Strict module boundaries.

Risk has veto power. Exchange clients are interchangeable behind the factory. Tests live alongside the modules they protect.

Auto-Trader/
├── main.py                  — FastAPI app entry · Uvicorn runner
├── requirements.txt         — Pinned deps
├── Dockerfile
├── docker-compose.yml
├── .env.example             — Template (committed)
├── .env                     — Secrets (gitignored)
├── .gitignore
├── README.md
│
├── app/
│   ├── config.py            — Pydantic settings, loads .env
│   ├── models.py            — Trade, Signal, DailyStats
│   └── database.py          — Async engine, WAL init
│
├── app/api/
│   ├── webhook.py           — POST /webhook · dedup · validation
│   └── health.py            — GET /health
│
├── app/strategy/
│   ├── signal_handler.py    — Parse · validate · deduplicate
│   └── signal_models.py     — Pydantic payload models
│
├── app/execution/           — ⭐ factory pattern (v3)
│   ├── base_client.py       — AbstractExchangeClient ABC
│   ├── exchange_factory.py  — Reads ACTIVE_EXCHANGE → client
│   ├── binance_client.py    — OCO orders · testnet support
│   ├── kraken_client.py     — Conditional close · paper mode
│   └── order_manager.py     — Exchange-agnostic dispatch
│
├── app/risk/                — ⭐ VETO power
│   ├── risk_manager.py      — Pre-trade checks · sizing
│   └── circuit_breaker.py   — Daily loss · drawdown · cooldown
│
├── app/alerts/
│   ├── telegram_bot.py      — Notifications · /commands
│   └── templates.py
│
├── app/recovery/
│   └── state_reconciler.py  — DB ↔ exchange on boot
│
├── tests/
│   ├── test_risk_manager.py
│   ├── test_exchange_factory.py
│   ├── test_binance_client.py
│   ├── test_kraken_client.py
│   ├── test_signal_handler.py
│   ├── test_webhook.py
│   └── conftest.py          — Mock exchanges (both)
│
└── logs/                    — Runtime logs (gitignored)

Withdraw is OFF. Always.

API keys never touch code or the database. The bot's exchange key must have Withdraw permission disabled — verified on startup. Anything less and the bot refuses to boot.

Zero orphan tolerance.

On every boot, the reconciler compares the SQLite trade log with the exchange's open positions. Orphans halt the bot and notify — never auto-closed. Humans decide.

1. Read ACTIVE_EXCHANGE from config
   Instantiate that client. No multi-exchange ambiguity at boot.
2. Query open positions
   Via get_open_positions() on the active exchange.
3. Cross-reference with DB
   Compare exchange-side state with the last known DB snapshot.
4. If orphan found → halt + alert
   Log a WARNING, fire a Telegram alert, stop trading. The user decides whether to keep, exit, or reconcile.
5. Load daily P&L from DB
   So the daily-loss limit picks up where it left off — restarts don't reset the budget.
6. Verify pair availability
   Confirm the trading pair is still listed on the active exchange before resuming.

Docker on a VPS near the exchange.

Recommended hosting: Hetzner, DigitalOcean, or Vultr in Frankfurt or Dubai. Lower latency to Binance Frankfurt = faster signal-to-fill.

docker-compose

services:
  bot:
    build: .
    env_file: .env
    ports: ["8000:8000"]
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout:  5s
      retries:  3
    volumes:
      - ./data:/app/data        # SQLite + logs
      - ./logs:/app/logs

Going live

1. Run 7+ consecutive days in testnet (or paper for Kraken) with the strategy you intend to use live.
2. Verify Telegram alerts fire on every state change.
3. Confirm circuit breakers are armed — try forcing a daily loss in testnet to watch them trip.
4. Set TRADING_MODE=live in .env. The bot will prompt you to type I-UNDERSTAND-THE-RISK to confirm.
5. Restart. The bot will report live mode in /health and the Telegram startup message.

Three-phase delivery plan.

v1 ships reliable execution. v2 adds professional features (multi-pair, futures, dashboards, monitoring). v3 evolves into an AI quant platform.

Spec revisions.

Newest first. Backwards-incompatible changes are flagged.

Common questions.