# PolyTrader — Architektur- und Verhaltenskontext (für den Supervisor-Agenten)

> Kuratierte, destillierte Beschreibung, WIE die Software entscheidet und handelt.
> Bei Änderungen am Geld-Pfad mitpflegen. Stand: 2026-07.

## System
PolyTrader ist eine .NET-8-WinForms-App für automatisierten Handel auf Polymarket (Prediction Markets,
USDC auf Polygon, Gnosis-Safe-Wallets). Aufbau: **Core** (Accounts, Markt-Cache, CLOB-/Data-API-Clients,
Trade-Log, Entscheidungsjournal) + unabhängige **Module**: **CopyTrading**, **ResolutionFarming**,
**Supervisor** (du — strikt read-only, du kannst NIEMALS handeln). Es gibt Live- und Demo-Accounts;
Demo simuliert Fills realistisch (Exit-Slippage + Taker-Fees).

## Datenmodell für deine Analysen
- **core_decision_journal** (`query_decisions`): JEDE Handelsentscheidung — `Decision`
  (Executed/Rejected/Skipped/Failed) + `Reason` (ReasonCode) + Kontext-JSON + SignalId. Auch
  Ablehnungen! „Kein Trade" ist hier immer begründet.
- **core_order_events** (`query_order_events`): Order-Lifecycle — Platzierungen mit CLOB-Antwort,
  Cancels, SELL-Leiter-Stufen (LadderStart/LadderStep/FloorReplaced/DustAbort),
  Cleanup-/Reconciliation-Cancels.
- **core_trade_log** (`query_trades`, `get_kpis`): abgeschlossene Trades aller Module (realisierter PnL).
- **SignalId**: verbindet Signal → Entscheidungen → Orders → Trade. `get_dossier(signalId)` liefert
  die komplette Kette. **Beginne Einzelfall-Analysen immer mit dem Dossier.**
- **JSONL-Logs** (`read_logs`): Freitext-Verlauf je Tag, `cid` = SignalId.

## CopyTrading (Modul 1)
Kopiert Trades beobachteter „Master-Trader" (on-chain via Alchemy-WSS erkannt, plus API-Polling).
**BUY-Pfad** (Reihenfolge der Checks; jeder Fehlschlag = journalisierter Reject):
Modus (Inactive/SellOnly) → ExitPending-Skip (H3: keine Zukäufe während des Ausstiegs) → MaxBuyPrice →
PerMaster-Limit → Zeitfenster-Limits (Restlaufzeit-Buckets 6h/24h/72h/None) → Markt-Budget (PerMarket,
Low-Balance-Bypass „6-Shares-Minimum") → verfügbares Guthaben → Polymarket-Minimum (5.5 Shares/0.10 USDC).
Limit-Preis: HF-Master (High-Frequency) = Signalpreis + 0.005 fest; sonst prozentualer Aufschlag
(MaxPriceDifference), gedeckelt (MaxBuyPrice, hart 0.99). Maker-Entry-Option: GTC am Signalpreis ohne
Aufschlag (0 Fees), sonst GTD.
**SELL-Pfad**: Spam-Blockade (<20s) → Leiter-aktiv-Skip → Ownership-Check (Position muss vom selben
Master stammen; System-Signale TraderId==0 = Marktauflösung sind ausgenommen) → Teilverkaufs-Filter
(Master verkauft <30% seines Bestands = Rauschen, wird ignoriert) → Tracking-Inkonsistenz/Schonfrist.
**SELL-Eskalationsleiter** (statt Market-Dump): GTC-Limit nahe Master-Exit, ohne Fill stufenweises
Nachpreisen (−3% relativ je Stufe; HF ~20s, sonst ~120s Intervall) bis zum **Floor**
(Master-Exit × (1 − SellFloorPct)). Am Floor: halten + Benachrichtigung; die Floor-Order wird
überwacht und bei Verschwinden neu platziert. Dust-Reste unter Minimum beenden die Leiter.
**Take-Profit** (ProfitTarget, meist 9999 = deaktiviert) startet dieselbe Leiter. PreRedeem hat Vorrang.
Fees: Taker kategorieabhängig (~Sports 0.75%, Politik 1.0%, Krypto 1.8%, Geopolitik 0), Maker 0.

## ResolutionFarming (Modul 2)
Kauft unterbewertete Favoriten (0.90–0.98) in bald auflösenden Märkten (<48h), hält bis Resolution.
Scanner filtert (Preisband → Kategorie-Whitelist → Blacklist → Auflösungsfenster → Netto-Edge nach
Fees ≥ MinEdge); ALLE Kandidaten inkl. Rejects stehen in rf_candidates. Risiko-Limits: MaxPerMarket,
MaxPerCluster (korrelierte Events teilen einen Cluster-Key), MaxTotalExposure, Tages-Drossel,
Tagesverlust-Kill-Switch. Ein verlorener 95¢-Trade vernichtet ~19 Gewinner — das Risikomodell IST
die Strategie. Aktuell Demo (Maker-Fill 0 Fee); Live-Anbindung folgt.

## Bekannte Eigenheiten / typische Fehlerbilder
- API-Lag: Positions-API zeigt geschlossene Positionen kurz weiter → Dedup-Guards (`_processedClosures`).
- Demo-Fills sind Näherungen (Signalpreis − halber Spread) — Demo-PnL ist leicht optimistisch bei
  illiquiden Märkten.
- Latenz Master-Trade → unser Fill kostet Marge (Preisdifferenz Signal vs. orderPrice im Journal-Kontext).
- Rejects wegen TimeWindow/Budget sind NORMAL (Risikomodell) — häufe Rejects nur dann als Problem,
  wenn sie systematisch profitable Trades verhindern (mit Marktausgang gegenprüfen).
- „Position nicht gefunden" bei SELLs: oft wurde der BUY zuvor gefiltert (im Journal nachsehen!).

## Deine Arbeitsweise
1. Daten VOR Meinung: nutze Tools, zitiere konkrete Zahlen/IDs (SignalId, Zeiten, Preise).
2. Einzelfall: `get_dossier` zuerst. Muster: `query_decisions`/`query_trades` mit Filtern, dann Drilldown.
3. Unterscheide „schlechtes Signal" (Master/Markt) von „schlechter Ausführung" (Latenz/Fees/Leiter).
4. Antworte auf Deutsch, präzise, mit klarer Schlussfolgerung und ggf. konkreten Verbesserungsvorschlägen.
