# Crypto_Agent

Crypto_Agent is the local JARVIS/Hermes-controlled research and paper-trading stack for HyperLiquid.

Current production posture:

```text
mode=paper_only
live_order_allowed=false
mainnet_signed_action=false
Tiny/Normal Live: not approved
```

The old monolithic `AutoTrader.py` style direct-order architecture is **not** the live core. The supported target architecture is the modular `src/` stack: market data, strategy, risk gates, paper lifecycle, execution/reconcile, reporting, and watchdogs.

## Operating Modes

| Mode | Purpose | Orders allowed? | Notes |
|---|---|---:|---|
| `READ_ONLY` | Collect/account/market/reporting only | No | Default for diagnostics and context collection. |
| `PAPER` | Paper lifecycle simulation | No live orders | Current active mode for v76 strict. |
| `TESTNET` | Future exchange-test mode | Testnet only | Not a production-live substitute. |
| `SHADOW_LIVE` | Observe real market and compare decisions | No autonomous live orders | Requires explicit approval before use. |
| `TINY_LIVE` | Very small live trial | Only after explicit approval | Currently blocked. |
| `NORMAL_LIVE` | Scaled live operation | Only after separate approval | Not implemented/approved. |

Hard invariants:

```text
No order without exchange-level stop.
No order on reconcile uncertainty.
No order during API degraded state.
No martingale.
No averaging down.
No risk increase without explicit user approval.
Daily/weekly loss gates are hard gates.
Max open positions are hard gates.
Secrets must never be logged or committed.
```

## Target Build Plan Status

The implementation plan in `docs/260629_bot_umsetzungsplan_extracted.md` defines eight phases.

| Phase | Name | Status |
|---:|---|---|
| 1 | Repo and runtime consolidation | Closed v1: README, runtime runbook, architecture doc, legacy guard, and live invariants are documented. |
| 2 | Market Snapshot Layer | Closed v1: HyperLiquid read-only context, normalized `market_snapshot.v1`, derivatives, CoinGecko fundamentals, L2 depth/impact-slippage, TradingView research sentiment context, notional liquidity scoring, and Confluence Light exist. Latest snapshot can gate v76 Paper entries. |
| 3 | Confluence Score Engine | Closed v1: versioned weights, component scores, risk/sentiment/portfolio placeholders, final_trade_score, and paper-only v76 strict gate exist. |
| 4 | Entry improvement | Closed v1: strict anti-chase/retest, VWAP-distance, ATR-pump, upper-wick/exhaustion, derivatives-crowding filters, and impact report exist. |
| 5 | Real Paper Lifecycle | Closed v1: entry, partial fills, stop, TP, trailing, time exit, maker/taker fees, depth-aware slippage, stop-gap slippage, funding, MFE/MAE, reporting and promotion gates exist. Larger evidence sample and deeper post-trade reconcile still required before live. |
| 6 | Three strategy sleeves | Closed v1: explicit intraday, swing-trend/retest, and portfolio/advisor sleeves plus read-only `strategy_sleeves.v1` scorecard exist. Swing and portfolio sleeves remain research/advisor-only until their own evidence exists. |
| 7 | Copytrading research | Closed v1: runtime watchlist, vault/wallet collectors, leader scorecard, follower fill model, read-only shadow-copy position engine, copy daily report and `copytrading_research.v1` scorecard exist. Live-copy remains blocked. |
| 8 | Portfolio advisor | Not implemented in this repo beyond architecture decision. |

## Runtime Runbook

See `docs/runtime_runbook.md` for active cron jobs, manual checks, legacy AutoTrader rules, and paper-only promotion criteria.

See `docs/architecture_runtime.md` for the Phase-1 target runtime architecture and legacy boundary.

## Core Commands

Run the full test suite:

```bash
python3 -m pytest -q
```

Run v76 paper runtime once:

```bash
python3 -m src.tools.v76_paper_runtime \
  --strategy-id candidate_v76_strict_live_candidate \
  --coins BTC,ETH,SOL,LINK,WLD,SUI,ENA,BCH \
  --iterations 1 \
  --json
```

Check/start the safe v76 paper supervisor:

```bash
python3 -m src.tools.v76_paper_supervisor \
  --ensure-running \
  --strategies strict,research_probe \
  --iterations 1440 \
  --interval-seconds 60 \
  --json
```

Build the HyperLiquid daily report:

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

Build the read-only Market Confluence Light snapshot:

```bash
python3 -m src.tools.market_confluence_report \
  --coins BTC,ETH,SOL,LINK,WLD,SUI,ENA,BCH \
  --json
```

TradingView paper bridge watchdog and community research collectors are paper/research-only. They must not be used as live execution authority.

## Current Strategy Posture

`v76 strict` remains the main intraday candidate, but it is **not live-ready**. The legacy synthetic paper PnL is preserved only as historical context. Promotion decisions must use true lifecycle exits only.

Current blockers observed in the lifecycle scorecard:

```text
lifecycle_pnl_not_positive
lifecycle_winrate_below_threshold
legacy_synthetic_exits_ignored
```

Live remains blocked until realistic lifecycle evidence, reconcile, stops, loss gates, kill-switch, alerts, shadow/confirm testing, and explicit user approval are all satisfied.