# JARVIS Trader Desk v1

## Zweck

Der Trader Desk ist die professionelle, **read-only** Entscheidungs- und Vorstufe für Tiny Live Autonomy auf Hyperliquid.

Er ersetzt keine Safety-Gates und sendet keine Orders. Er erstellt strukturierte Trade-Pläne aus:

- Hyperliquid Market Snapshot / Confluence
- Chart-/Trend-/Momentum-/Volatilitätsdaten
- Liquidität, Spread, L2-Impact
- Funding, Premium, Open Interest
- CoinGecko Fundamentals
- TradingView Community Research Context
- Tiny-Live-Mandat und Risikolimits

## Output

Pro Coin erzeugt der Desk einen `TradePlan`:

- `action`: `no_trade`, `watch_shadow`, `tiny_live_candidate`
- `direction`: `long`, `short`, `none`
- `score`
- Setup-Typ
- Entry-Zone
- Stop-Loss
- TP1/TP2/Management
- Risk/Reward
- Blocker und Evidenz

## Sicherheitsgrenzen

Immer:

```text
live_order_allowed=false
mainnet_signed_action=false
```

Ein `tiny_live_candidate` ist **keine Order-Freigabe**. Vor jeder Mainnet-Order braucht es weiterhin:

```text
Final Preflight
Reconcile grün
Kill-Switch inaktiv
API/DataQuality grün
Stop-/Risk-Gates aktiv
Tiny live runtime gate explizit gesetzt
```

## Mandat v1

```text
long-only für Tiny Live
BTC, ETH, SOL, LINK tiny-live-fähig
Shorts nur Shadow/Watch
Max Notional pro Trade: 15 USDC
Max Gesamt-Notional: 45 USDC
Max offene Trades: 3
```

## CLI

Aus vorhandenem Market-Confluence-Report:

```bash
python3 -m src.tools.trader_desk_report \
  --from-report runtime/reports/market_confluence_latest.json
```

Frischen read-only Snapshot bauen:

```bash
python3 -m src.tools.trader_desk_report --env mainnet
```

JSON-Ausgabe:

```bash
python3 -m src.tools.trader_desk_report --json
```

Output:

```text
runtime/reports/trader_desk_latest.json
```

## FinanceManager Bridge

Der Trader Desk exportiert einen sicheren Bridge-Snapshot, den FinanceManager/JARVIS Dashboard als `CryptoTrader`-Modul lesen und als Hyperliquid-Trader-Desk-Karten rendern kann:

```bash
python3 -m src.tools.trader_desk_report \
  --env mainnet \
  --export-finance
```

Default-Ziel:

```text
/home/agent/jarvis_runtime/finance-system/crypto_trader/trader_desk_latest.json
/home/agent/jarvis_runtime/finance-system/crypto_trader/trader_desk_latest.md
```

Bridge-Schema:

```text
finance_crypto_trader_desk_bridge.v1
```

Jede `trade_intent` Karte enthält:

```text
intent_id
portfolio_id=hyperliquid-usdc-derivatives
source_engine=jarvis_trader_desk_v1
strategy_id=trader_desk_multi_signal_v1
coin / side / signal / mode
entry_zone / stop_loss / take_profit
confidence_score / evidence / blockers
execution_allowed=false
dashboard_executes_orders=false
mainnet_signed_action=false
```

Die FinanceManager-Seite darf daraus Signal-/Approval-Karten bauen, aber **keine Exchange-Order ausführen**.

## Shadow Runner

Der Shadow Runner macht den Desk beobachtbar, ohne Live-Trading zu aktivieren:

```bash
python3 -m src.tools.trader_desk_shadow_runner \
  --env mainnet \
  --coins BTC,ETH,SOL,LINK \
  --iterations 1 \
  --json
```

Er schreibt:

```text
runtime/experiments/trader_desk_shadow/trader_desk_latest.json
runtime/experiments/trader_desk_shadow/decision_journal.jsonl
runtime/experiments/trader_desk_shadow/outcome_journal.jsonl
runtime/experiments/trader_desk_shadow/runtime_health.jsonl
runtime/experiments/trader_desk_shadow/state.json
```

Zusätzlich exportiert er standardmässig denselben FinanceManager-Bridge-Snapshot nach:

```text
/home/agent/jarvis_runtime/finance-system/crypto_trader/trader_desk_latest.json
/home/agent/jarvis_runtime/finance-system/crypto_trader/trader_desk_latest.md
```

Sicherheitsgrenzen des Runners:

```text
paper_only=true
live_order_allowed=false
mainnet_signed_action=false
CTB_LIVE_TRADING_ALLOWED=true wird verweigert
```

Der Runner öffnet nur hypothetische Shadow-Positionen aus `watch_shadow`/`tiny_live_candidate` Plänen, journalisiert Stop-/TP-/Invalidierungs-Outcomes und liefert damit Evidenz für spätere Tiny-Live-Preflights. Er sendet keine Orders.

## Shadow Scorecard

Die Scorecard verdichtet Decision-/Outcome-Journals zu einer Dashboard-tauglichen Evidenz-Datei:

```bash
python3 -m src.tools.trader_desk_shadow_scorecard \
  --runtime-dir runtime/experiments/trader_desk_shadow \
  --json
```

Sie schreibt standardmässig:

```text
runtime/experiments/trader_desk_shadow/scorecard_latest.json
/home/agent/jarvis_runtime/finance-system/crypto_trader/trader_desk_scorecard_latest.json
```

Schema:

```text
trader_desk_shadow_scorecard.v1
```

Kennzahlen:

```text
decisions / tiny_live_candidates / watch_shadow / blocked
closed / wins / losses / scratch
win_rate_pct / realized_r / avg_r
open_shadow_positions
by_coin / by_action / by_setup / by_score_bucket
```

Auch diese Datei bleibt strikt read-only:

```text
paper_only=true
live_order_allowed=false
mainnet_signed_action=false
dashboard_executes_orders=false
```

## Tiny-Live Final Preflight v1

Der Final-Preflight ist die Bot-seitige Readiness-Prüfung für spätere Tiny-Live-Autonomie. Er liest Trader-Desk-Intent, Shadow-Scorecard und optional Reconcile-/Credential-/Testnet-Proofs und schreibt:

```text
/home/agent/jarvis_runtime/finance-system/crypto_trader/trader_desk_tiny_live_preflight_latest.json
```

CLI:

```bash
python3 -m src.tools.trader_desk_tiny_live_preflight \
  --bridge-path /home/agent/jarvis_runtime/finance-system/crypto_trader/trader_desk_latest.json \
  --scorecard-path /home/agent/jarvis_runtime/finance-system/crypto_trader/trader_desk_scorecard_latest.json \
  --reconcile-path /tmp/ctb_reconcile.json \
  --credential-matrix-path /tmp/ctb_credential_matrix.json \
  --testnet-proof-path /tmp/ctb_testnet_fill_stop_raw.json \
  --alert-proof-path /tmp/ctb_alert_proof.json \
  --output /home/agent/jarvis_runtime/finance-system/crypto_trader/trader_desk_tiny_live_preflight_latest.json \
  --json
```

Schema:

```text
trader_desk_tiny_live_preflight.v1
```

Hard Gates v1:

```text
current_intent
risk_limits
data_quality
shadow_sample
shadow_winrate
shadow_realized_r
read_only_reconcile
signed_credentials
testnet_execution_proof
alert_delivery
legacy_live_paths_blocked
live_env_disabled
```

Auch bei `preflight_status=pass` bleibt der Export strikt nicht-ausführend:

```text
execution_allowed=false
live_order_allowed=false
mainnet_signed_action=false
dashboard_executes_orders=false
```

Ein grüner Preflight ist nur eine technische Startvoraussetzung. Vor echter Mainnet-Ausführung muss der spätere Live-Runner alle Gates direkt erneut prüfen.

## Action-Logik

```text
Score < 70 oder Hard Blocker -> no_trade
Score 70-79 -> watch_shadow
Score >= 80 + Coin erlaubt + Long -> tiny_live_candidate
Short unter Tiny-Live-Mandat -> watch_shadow
```

Hard Blocker:

```text
stale_data
low_reliability
weak_liquidity
spread_unknown/spread_too_wide
l2_unavailable
impact_slippage_too_high
volatility_too_high
risk_score_too_low
confluence_below_threshold
```

## Nächster Ausbau

1. Shadow Runner periodisch per Scheduler/Cron betreiben und nach genügend Ticks Score-vs-Outcome auswerten
2. Anbindung an `tiny_autonomous_live_runtime` als reiner Signal-Lieferant
3. Final Preflight `tiny-autonomous-live`
4. Testnet forced fill/stop/reconcile
5. Tiny live start nur bei grünen Gates