Arnold Trader

Arnold Trader is an automated cryptocurrency trading platform delivered as a Telegram Mini App. It combines a Python/FastAPI backend running multiple trading engines with a React single-page application frontend, all deployed on Hetzner PM2 with auxiliary daemons on Hetzner.

Tech Stack

Layer	Technology
Backend	Python 3.12, FastAPI, Uvicorn
Frontend	React 19, Vite 8, Tailwind CSS 4, lightweight-charts
Database	PostgreSQL (asyncpg connection pool, Alembic migrations)
Cache / Rate Limit	Redis (SlowAPI middleware, 120 req/min default)
Exchange	Bybit (primary), Binance, OKX, Bitget, Hyperliquid via CCXT
ML Pipeline	LightGBM, scikit-learn, ONNX Runtime, pandas-ta
Telegram	TWA SDK (@twa-dev/sdk), Telethon (signal copier)
Wallet	TON Connect (tonconnect-ui-react)
Monitoring	Sentry (FastAPI integration), structured JSON logging
Deployment	Hetzner PM2 (Docker, auto-restart on failure), Hetzner (PM2 daemons)

Key Features

• Grid Trading Engine -- Bidirectional grid on BTC/ETH/SOL with linear (futures) and spot modes. AI advisor uses OpenRouter to dynamically adjust grid range, profit targets, levels, and rebalance frequency every 15 minutes.
• Strategy Runner -- 22 registered strategies including scalping, momentum, mean reversion, DCA, arbitrage, funding rate, liquidation hunter, trend sniper, order flow, smart scalper, AI signals, and more. Each runs on a configurable interval with per-user paper/live mode.
• AI Signal Engine -- ML ensemble (LightGBM + ONNX) trained weekly on BTC price data. Generates buy/sell signals with confidence scores. Paper-trading gate validates AI accuracy before live execution.
• Signal Copier -- Monitors 54 Telegram channels via Telethon, parses structured and free-form signals, auto-executes on Bybit.
• Copy Trading -- Follow top traders from the Bybit leaderboard. Risk-managed position mirroring with configurable allocation.
• Portfolio Analytics -- Performance snapshots every 6 hours, PnL calendar, monthly returns, equity curve, strategy-level breakdown.
• Market Regime Detection -- Classifies market as bullish/bearish/ranging every 4 hours. Strategies scale positions and budgets based on regime.
• Risk Management -- Three-level kill switch (env var), max drawdown stop, trailing stops, multi-level take-profit, dynamic leverage based on volatility, position monitoring every 5 seconds.
• Lite Orchestrator -- Automated budget rebalancing every 4 hours. Boosts winning strategies, reduces losers, adjusts grid parameters based on volatility.
• Kairos Agent -- Always-on background watchdog running on Hetzner via PM2. Monitors errors, balance drift, stale positions, and PM2 crashes. Sends Telegram alerts and auto-restarts processes.
• Backtester -- Historical strategy validation against kline data.
• Billing and Referrals -- Performance fee tracking and referral system.
• Onboarding Wizard -- Risk quiz and exchange key setup flow for new users.
• Internationalization -- Multi-language support via i18n module.

Quick Start

Prerequisites

• Python 3.12+
• Node.js 20+ (for frontend build)
• PostgreSQL 15+
• Redis (optional, falls back to in-memory rate limiting)

Backend

cd backend
python -m venv .venv
source .venv/bin/activate   # or .venv\Scripts\activate on Windows
pip install -r requirements.txt

# Configure environment
cp .env.example .env        # then fill in required values
# Required: DATABASE_URL, BYBIT_API_KEY, BYBIT_API_SECRET, TELEGRAM_BOT_TOKEN, TELEGRAM_USER_ID
# Optional: SENTRY_DSN, REDIS_URL, OPENROUTER_API_KEY

# Run database migrations
alembic upgrade head

# Start the unified service (all daemon threads)
python main.py

Frontend

cd frontend
npm install
npm run dev            # development server at localhost:5173
npm run build          # production build -> ../backend/static/

The production frontend is built and copied to backend/static/, where the FastAPI backend serves it as a single-page application. All non-API routes fall through to index.html.

Environment Variables

Variable	Required	Description
DATABASE_URL	Yes	PostgreSQL connection string
BYBIT_API_KEY	Yes	Bybit API key for trading
BYBIT_API_SECRET	Yes	Bybit API secret
TELEGRAM_BOT_TOKEN	Yes	Telegram bot token for notifications
TELEGRAM_USER_ID	Yes	Default Telegram user ID
PORT	No	HTTP port (default: 8000)
REDIS_URL	No	Redis URL for rate limiting
SENTRY_DSN	No	Sentry error tracking DSN
OPENROUTER_API_KEY	No	OpenRouter key for AI gates, AI agents, sentiment, grid advisor and Trading Assistant
ARNOLD_KILL_SWITCH	No	Set to 1 to halt all trading
DISABLE_TG_POLLING	No	Set to true to disable Telegram polling

Architecture Overview

The application runs as a single Python process (main.py) that spawns 13 daemon threads:

1. API Server -- FastAPI served by Uvicorn on port 8000 with 35+ routers
2. Telegram Bot -- Long-polling bot for commands and notifications
3. Grid Trader -- Autonomous grid trading engine (60s cycle)
4. Strategy Runner -- Multi-strategy analysis and execution (10s cycle)
5. Futures Engine -- Dedicated futures position management
6. Regime Detector -- Market regime classification (4h cycle)
7. Snapshot Collector -- Portfolio snapshots + rebalance checks (6h cycle)
8. Price Feeder -- Real-time prices via Bybit WebSocket with REST fallback (5s)
9. Daily Summary -- Telegram summary at 21:00 UTC
10. Position Monitor -- Trailing stop and take-profit checks (5s cycle)
11. Orchestrator -- Automated strategy budget rebalancing (4h cycle)
12. Onchain Signals -- On-chain data signal detection
13. Meme Sniper -- Currently disabled, handled by trend_sniper strategy

Additionally, Kairos and Signal Copier run as separate PM2 processes on Hetzner.

For detailed architecture documentation, see ARCHITECTURE.md.