Telegram → LLM → Binance Futures.
Real-time signal monitoring, AI-powered analysis, automated execution.
Version Python Docker Binance LLM
graph LR
A[📡 fattyfatclub] --> B[Regex Parse<br/>1ms]
B --> C[Gate 1<br/>Pre-LLM]
C --> D[🧠 LLM<br/>mimo-v2.5]
D --> E[Gate 2<br/>Hard Clamps]
E --> F[⚡ Order Exec]
F --> G[📈 Binance Futures]
F --> H[📱 Telegram Notif]
G --> I[🛡 Position Monitor<br/>10s loop]
| Metric | Value |
|---|---|
| Signal Source | @fattyfatclub (UNKNOWN TRADERS ACADEMY) |
| Exchange | Binance USDS-M Futures (isolated margin) |
| LLM | OpenCode Go · mimo-v2.5 |
| Deploy | Tencent VPS (sera) · Docker container |
| Version | v1.0.0 |
| Risk | 5ドル max pos · 10% risk · 30% daily loss limit |
Every Telegram message flows through 6 stages in ~2 seconds:
| Stage | What Happens | Cost |
|---|---|---|
| 1 Regex Parse | Extracts pair, direction, SL/TP in ~1ms | Free |
| 2 Gate 1 | Idempotency check, cooldown, whitelist | Free |
| 3 LLM Brain | Analyzes signal, decides ENTER/CLOSE/SKIP | ~1 API call |
| 4 Gate 2 | Clamps position size, leverage, daily loss | Free |
| 5 Execution | LIMIT entry + SL/TP placement | Binance API |
| 6 Notification | Telegram card with full trade details | Free |
⚡ Management commands (
sl to entry,tp1 booked,full, etc.) skip the LLM entirely and execute directly in ~200ms.
src/
├── main.py # Entry point — wires everything
├── orchestrator.py # Pipeline coordinator
├── listener.py # Telethon Telegram listener + bot commands
├── agent/
│ ├── parser.py # Regex signal parser (~1ms)
│ ├── agent.py # LLM brain (OpenCode Go)
│ └── gate.py # Safety Gates 1 & 2
├── exchange/
│ ├── base.py # Abstract exchange interface
│ ├── binance.py # Binance Futures REST API
│ ├── paper.py # Paper trading simulator
│ ├── validation.py # Pre-submission order validation
│ └── symbol_registry.py # Dynamic symbol cache
├── execution/
│ ├── order_service.py # Decision → orders + SL/TP
│ └── position_manager.py # Background 10s monitor loop
├── state/
│ ├── database.py # SQLite (WAL, auto-migration)
│ └── repositories.py # Repository pattern (11 repos)
├── api/
│ ├── server.py # FastAPI (15+ endpoints)
│ ├── auth.py # API key + HMAC + rate limiter
│ └── webhook.py # Trade event webhook
├── domain/models.py # Typed dataclasses
├── events/bus.py # In-process pub/sub
├── health/reporter.py # Periodic health checks
└── notifier/telegram.py # Bot API notifications
| Metric | Value |
|---|---|
| Signals Processed | 160+ |
| Trades Executed | 21 |
| Currently Open | PUMPUSDT LONG · AAVEUSDT LONG |
| Most Traded | KAITOUSDT (×ばつ) · 1000BONKUSDT (×ばつ) · PUMPUSDT (×ばつ) |
| Management Commands | 50+ |
| Database | SQLite · 14 tables · /data/trades.db |
Three independent layers — no single component can override the hard limits:
- ✅ Idempotency — same
message_idnever processed twice - ✅ Cooldown — 5min minimum gap per pair
- ✅ Whitelist — restrict to approved pairs
- 🛑 Max position: 5ドル hard cap
- 🛑 Max concurrent: 10 positions
- 🛑 Daily loss limit: 30%
- 🛑 Leverage ceiling: ×ばつ
- 🛑 SL direction validation
- 🛑 Portfolio leverage cap: ×ばつ
- 🔄 Price-based SL monitoring (for -4120 pairs)
- 🔄 Self-heal — re-attaches missing SL/TP
- 🔄 Orphan detection — verifies against exchange
- 🔄 Time-based exit — auto-closes after 48h
- 📱 Telegram notification on every close
Send these as private messages to your bot:
| Command | Description |
|---|---|
/check <pair> |
Price + 24h stats |
/balance |
Futures account balance |
/positions |
Open positions + PnL |
/positions add ... |
Manual entry (LONG/SHORT, qty, lev, price) |
/close <pair> |
Market-close position |
/pending |
Pending conditional signals |
/cancel <id> |
Cancel pending signal |
/health |
Full system health check |
/setport N |
Margin budget per trade |
/setleverage N |
Default leverage ceiling |
/version |
Bot version |
/help |
All commands |
Secure HTTP API on port 9090 for Hermes or external tools:
# Stats dashboard curl -s -H "X-API-Key: $KEY" http://localhost:9090/api/v1/stats # Pipeline trace by correlation ID curl -s -H "X-API-Key: $KEY" http://localhost:9090/api/v1/logs/{correlation_id} # Full trade trace with LLM interaction curl -s -H "X-API-Key: $KEY" http://localhost:9090/api/v1/trades/{id}
Auth: API key + HMAC-SHA256 for writes · Rate limited: 30 req/min/IP
# Clone git clone https://github.com/hernanda-git/UTbot.git cd UTbot # Install pip install -r requirements.txt # Configure cp .env.example .env # Edit .env with your Telegram API credentials, Binance API key, etc. # Dry-run first (analyzes without trading) # config.yaml → agent.auto_trade: false python src/main.py
📖 Full docs: SETUP.md · CONFIGURATION.md · DEPLOYMENT.md
| Doc | What |
|---|---|
| 🏗 Architecture | Full system architecture + DB schema |
| 📦 Setup | Step-by-step local + Fly.io setup |
| ⚙️ Configuration | All config keys |
| 🛡 Risk Management | Safety gates + risk controls |
| 🚀 Deployment | Fly.io + Docker deployment |
| 📡 Signal Parsing | Regex + LLM signal patterns |
| 🔌 API Reference | Exchange + HTTP API |
| 🛩 Fly Operations | Logs, SSH, health checks |
| 🤖 Agent Guide | AI agent maintenance runbook |
Read AGENTS.md first — it's the AI agent's guide to this project with code conventions, known pitfalls, agentic workflows, and deployment procedures.
Built with Hermes Agent · OpenCode Go (mimo-v2.5) · Binance USDS-M Futures
"The market is a signal. The bot is the trigger. You are the edge."