# trade-kuns — Live-Paper-Engine (Phase 3, Design)

**Datum:** 2026-06-10
**Status:** Umsetzung (User-Entscheidung: bewusster Paper-Probelauf)
**Basis:** Spec `2026-06-09-trade-kuns-design.md` §4.3–4.6, §6, §8

---

## 1. Kontext & Entscheidung

Das Walk-Forward-Gate wurde von keiner der 7 Varianten bestanden (siehe
`docs/walkforward-ergebnisse-2026-06-09.md`). Beste Variante: **long-only mit
fixen Spec-Default-Parametern** (Donchian 20 / ATR×3 / EMA 200 / ADX 20) —
OOS-PF 1.21, 249 Trades, MaxDD 16 %, Overfitting-Ratio 1.51; einziger
Fail: 11/32 Fenster mit PF < 0.5.

**Entscheidung (User, 2026-06-10):** Live-**Paper**-Engine bauen und diese
Variante im Paper-Probelauf validieren. Das Gate wird nicht aufgeweicht —
der Paper-Lauf *ist* die nächste Validierungsstufe. Kein echtes Geld, keine
Order-Ausführung, keine Schreib-API-Keys (Spec §10 unverändert).

## 2. Abweichungen von der Ursprungs-Spec

| Spec | Jetzt | Grund |
|---|---|---|
| Subdomain `trade.kuns.dev` | **`trading.kuns.dev`** | User-Vorgabe |
| Hono | **`Bun.serve`** | 6 GET-Routen, kein Framework nötig |
| Vue 3 + Vite Dashboard | **statische Single-Page** (Vanilla JS, Canvas-Chart) | kein Build-Step, kein Over-Engineering |
| Zitadel-JWT-Auth | **keine Auth** | API ist read-only (Paper-Daten, nichts Sensibles); Schreib-Endpoints (`toggle`/`reset`/`config`) entfallen in v1 |
| Port 8080 | 8080 | unverändert |

## 3. Architektur

Ein Bun-Prozess (`src/server/index.ts`): HTTP-Server + 5-min-Loop.

```
src/server/
  live/
    engine.ts        LiveEngine: Zyklus-Orchestrierung, Recovery, Persistenz
    process-cycle.ts pure Funktion: (candles, state) → actions (Entries/Exits/Decisions/Equity)
  api/
    server.ts        Bun.serve: /health, /api/*, statisches Dashboard
  db/schema.ts       + positions, paper_trades, decision_logs, bot_state, equity_snapshots
public/index.html    Dashboard
```

**Ein Code-Pfad-Prinzip bleibt:** `process-cycle.ts` nutzt exakt dieselben
puren Funktionen wie der Backtest-Runner (`computeIndicators`, `evaluateAt`,
`updateChandelier`, `sizePosition`, `Portfolio`) mit identischer Semantik:
4h-Entries (Close > Donchian-High(20) ∧ Close > EMA-200 ∧ ADX ≥ 20),
15m-Stop-Checks (Low ≤ Stop → Exit, Gap → Open als schlechterer Fill),
Chandelier-Update pro abgeschlossener 4h-Bar, Fees 0.1 % + Slippage 5 bps.

## 4. Zyklus (alle 5 Minuten)

1. **Fetch:** je Pair neueste 15m-Candles von Crypto.com (Lücke seit Cursor,
   `end_ts`-Paginierung wie Backfill, max 300/Request), nur abgeschlossene
   (`ts + 15m ≤ now`) → `candles` (Dedup via PK).
2. **Load:** je Pair letzte ~6500 15m-Candles (≈ 400 4h-Bars — Warmup für
   EMA-200 + Donchian) aus DB.
3. **Process** (pure, deterministisch): alle 15m-Candles mit `ts > cursor`
   chronologisch gemergt (Tie-Break PAIRS-Reihenfolge wie Runner):
   - neue abgeschlossene 4h-Bars des Pairs: Chandelier-Update → Entry-Evaluation
     (jede Evaluation → DecisionLog, inkl. Blockierungsgrund/Sizing-Block)
   - 15m-Stop-Check der offenen Position
   - Equity-Punkt einmal pro 4h-Bucket
4. **Persist** (eine Transaktion): Positions-Upsert/Delete, Trades,
   DecisionLogs, Equity-Snapshots, `bot_state` (cash, cursor).
5. **Outcome-Backfill:** `decision_logs` mit NULL-Outcomes füllen, sobald
   Candles 4h/24h/72h später vorliegen (Edge-Frühindikator, Spec §5.5).

**Initialisierung (erster Start):** `bot_state` mit 1000 USDT Cash,
Cursor = neueste abgeschlossene 15m-Candle. Keine historische Replay —
der erste mögliche Entry ist der nächste frische 4h-Close.

**Restart-Recovery (Spec §6):** Positionen + Cash + Cursor aus DB; verpasste
Candles werden nachgeholt und Stops rückwirkend geprüft — identisch zum
Normalzyklus, da der Prozess-Schritt nur vom Cursor abhängt.

**Fehler:** API-Fehler eines Pairs → Pair in diesem Zyklus überspringen,
andere laufen weiter; Fetch-Retry (3×, Backoff) existiert im Client.
DB-Fehler → Zyklus abbrechen, Status rot. Überlappende Zyklen durch
`running`-Flag verhindert. Letzter Zyklus-Status sichtbar in `/api/portfolio`.

## 5. Datenbank (neu)

- `positions` — pair (PK), side, qty, entry_ts, entry_price, entry_cost,
  initial_stop, stop, trail_extreme, risk_amount
- `paper_trades` — id, pair, side, entry/exit (ts+price), qty, pnl, r, exit_reason
- `decision_logs` — id, pair, bar_ts (4h), signal, blocked_by, close, atr, adx,
  donchian_high, trend_ema, price_after_4h/24h/72h (nullable), unique(pair, bar_ts)
- `bot_state` — id=1, cash, start_capital, cursor_ts, updated_at
- `equity_snapshots` — ts (PK, 4h-Bucket), equity, cash

## 6. API & Dashboard

| Route | Inhalt |
|---|---|
| `GET /health` | `{ok, lastCycle, cycleError}` — Coolify-Healthcheck |
| `GET /api/portfolio` | Equity, Cash, offene Positionen (inkl. Stop, unrealized PnL), Zyklus-Status |
| `GET /api/trades?limit` | abgeschlossene Trades, neueste zuerst |
| `GET /api/decisions?pair&limit` | DecisionLog inkl. Outcomes |
| `GET /api/stats` | PF, WinRate, MaxDD, avgR, Trade-Anzahl, Equity-Kurve |
| `GET /api/candles?pair&tf=15m|4h&limit` | Candles fürs Dashboard |

Dashboard: eine statische Seite, 30-s-Polling. KPI-Leiste (Equity, PnL, PF,
WinRate, MaxDD), Equity-Kurve (Canvas), Tabellen: offene Positionen, Trades,
letzte Decisions je Pair.

## 7. Tests

- `process-cycle`: Determinismus; Entry auf 4h-Close; Stop-Check inkl.
  Gap-Fill; Cursor-Idempotenz (zweiter Lauf ohne neue Candles = no-op);
  Restart-Äquivalenz (ein Lauf über N Candles ≡ zwei Läufe mit Cut dazwischen).
- Engine-Persistenz gegen Test-DB wird nicht automatisiert (kein CI mit DB);
  manuelle Verifikation beim Deploy.

## 8. Deployment

- Dockerfile `oven/bun:1.3`, Start: Migrationen → Server, Port 8080,
  Healthcheck `/health`.
- Coolify-App `trade-kuns`, Domain `https://trading.kuns.dev`, Netz `coolify`.
- `DATABASE_URL=postgres://mika:…@l8kogcggsc80sgcgk8kswww4:5432/tradekuns`
  (shared-postgres über Coolify-Docker-Netz; vom Host aus weiterhin
  `localhost:54320`).
- Backfill läuft weiter vom Host (`bun run backfill`) oder implizit über den
  Lücken-Fetch des Loops.