docs: README with architecture, data inputs, decision engine, infrastructure map
This commit is contained in:
drjones
114
README.md
Normal file
114
README.md
Normal file
@@ -0,0 +1,114 @@
|
|||||||
|
# K4LSH1_OPS
|
||||||
|
|
||||||
|
Multi-coin LLM-driven 15-minute binary options trading bot on Kalshi. Three independent bots trade DOGE, SOL, and ETH simultaneously using a two-tier LLM decision engine.
|
||||||
|
|
||||||
|
## Architecture
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────────────────────────┐
|
||||||
|
│ K4LSH1_OPS FLEET │
|
||||||
|
├──────────┬──────────┬───────────────────────────────────────────┤
|
||||||
|
│ DOGE 🐶 │ SOL 🔮 │ ETH 💎 ← 3 independent processes │
|
||||||
|
│ .154 │ .71 │ .189 ← proxy-backed Binance intel │
|
||||||
|
│ doge.db │ sol.db │ eth.db ← isolated tick/decision DBs │
|
||||||
|
└──────────┴──────────┴───────────────────────────────────────────┘
|
||||||
|
│ │
|
||||||
|
▼ ▼
|
||||||
|
┌──────────────┐ ┌──────────────────┐
|
||||||
|
│ qwen3.5:4b │ borderline│ ornith:latest │
|
||||||
|
│ MacBook │──────────▶ │ GamingPC .186 │
|
||||||
|
│ (0.4s gate) │ escalate │ RTX 3070 (0.86s)│
|
||||||
|
└──────────────┘ └──────────────────┘
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌──────────────────────────────────────────────┐
|
||||||
|
│ Kalshi V2 API (api.elections.kalshi.com) │
|
||||||
|
│ /portfolio/events/orders — bid/ask format │
|
||||||
|
└──────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
## Data Inputs Per Decision
|
||||||
|
|
||||||
|
Every 5-minute decision cycle feeds the LLM a full market snapshot:
|
||||||
|
|
||||||
|
| Source | Data | Frequency |
|
||||||
|
|--------|------|-----------|
|
||||||
|
| Kraken | Spot price (per coin) | 20s tick |
|
||||||
|
| Binance (via proxy) | 24h change, 24h range, 24h volume | 5min cached |
|
||||||
|
| Kraken OHLC | 1m/5m/15m/1h/2h multi-timeframe trend | per cycle |
|
||||||
|
| SQLite ticks | RSI(14) on 1m and 5m timeframes | per cycle |
|
||||||
|
| Kalshi orderbook | YES/NO ask, spread, depth imbalance | per cycle |
|
||||||
|
| Fear&Greed Index | Market sentiment (0-100) | 5min cached |
|
||||||
|
| Mempool.space | BTC fast fee (sat/vB) | 5min cached |
|
||||||
|
| Orders DB | Per-coin 24h win rate, recent performance | per cycle |
|
||||||
|
| Volatility calc | Market regime (choppy/trending/normal) | per cycle |
|
||||||
|
|
||||||
|
## Decision Engine
|
||||||
|
|
||||||
|
### Two-Tier LLM Voting
|
||||||
|
|
||||||
|
1. **Fast gate** — `qwen3.5:4b` on MacBook (0.4s). Handles clear signals. If confident (≥0.70) → trade immediately.
|
||||||
|
2. **Deep verify** — `ornith:latest` on GamingPC RTX 3070 (0.86s). Called when gate is borderline (<0.70 or unclear). Final verdict.
|
||||||
|
|
||||||
|
### Safety Gates (checked before any order)
|
||||||
|
|
||||||
|
- **RSI contrarian** — RSI > 85 → auto-fade DOWN, RSI < 15 → auto-fade UP (no LLM needed)
|
||||||
|
- **BTC macro correlation** — Won't short alts when BTC 24h > +0.5% unless conf > 0.78
|
||||||
|
- **Adaptive confidence** — Win rate adjusts minimum confidence (loses → tighter, wins → relaxed)
|
||||||
|
- **Self-adapting overrides** — qwen analyzes last 20 resolved bets every 10 min, tunes thresholds
|
||||||
|
- **Daily loss cap** — Hard stop at configurable daily loss limit
|
||||||
|
- **Market expiration guard** — Verifies market open before placing order
|
||||||
|
|
||||||
|
### Position Sizing
|
||||||
|
|
||||||
|
- Max $1.00 per trade (configurable via `max_spend_cents`)
|
||||||
|
- Confidence-scaled contracts: <0.70 = x1, 0.70-0.80 = x2, 0.80-0.90 = x3, >0.90 = x4
|
||||||
|
- Auto-capped so `contracts × price ≤ max_spend`
|
||||||
|
- Taker at ask when ≤ 55¢, maker at 50¢ when book is thin
|
||||||
|
|
||||||
|
### Hedge Engine
|
||||||
|
|
||||||
|
Scans every cycle for open positions where buying the opposite side locks ≥8¢ profit. Auto-executes counter-orders.
|
||||||
|
|
||||||
|
## Files
|
||||||
|
|
||||||
|
| File | Purpose |
|
||||||
|
|------|---------|
|
||||||
|
| `bot.py` | Main bot — decision engine, Kalshi client, order placement |
|
||||||
|
| `dashboard.py` | Flask dashboard — fleet view at `/fleet`, single-coin at `/` |
|
||||||
|
| `test_bot.py` | Unit tests — momentum, RSI, hedge, decision logic, LLM parsing |
|
||||||
|
| `config.json` | Base config (shared defaults) |
|
||||||
|
| `doge.json` / `sol.json` / `eth.json` | Per-coin configs with proxies, LLM URLs, DB paths |
|
||||||
|
|
||||||
|
## Quick Start
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Launch all 3 bots
|
||||||
|
cd ~/kalshi-bot
|
||||||
|
.venv/bin/python bot.py --config doge.json --lock doge &
|
||||||
|
.venv/bin/python bot.py --config sol.json --lock sol &
|
||||||
|
.venv/bin/python bot.py --config eth.json --lock eth &
|
||||||
|
|
||||||
|
# Launch dashboard
|
||||||
|
.venv/bin/python dashboard.py
|
||||||
|
|
||||||
|
# Run tests
|
||||||
|
.venv/bin/python test_bot.py
|
||||||
|
```
|
||||||
|
|
||||||
|
## Dashboard
|
||||||
|
|
||||||
|
- **Fleet view**: `http://localhost:5053/fleet` — all 3 coins, color-coded, PNL, decision trace
|
||||||
|
- **Single coin**: `http://localhost:5053` — controls, orderbook, momentum chart
|
||||||
|
- **API**: `GET /api/fleet` — all coins JSON, `GET /api/state` — single coin state
|
||||||
|
|
||||||
|
## Infrastructure
|
||||||
|
|
||||||
|
| Component | Host | Purpose |
|
||||||
|
|-----------|------|---------|
|
||||||
|
| MacBook | localhost:11434 | qwen3.5:4b fast gate |
|
||||||
|
| GamingPC | 10.30.20.186:11434 | ornith:latest deep verify (RTX 3070) |
|
||||||
|
| proxy1 | 10.30.20.154:3128 | DOGE Binance intel (Brazil exit) |
|
||||||
|
| proxy2 | 10.30.20.71:3128 | SOL Binance intel (EU exit) |
|
||||||
|
| proxy3 | 10.30.20.189:3128 | ETH Binance intel (Brazil exit) |
|
||||||
|
| Gitea | 10.30.20.149:3000 | Code repo |
|
||||||
Reference in New Issue
Block a user