## Ergebnis

### Bestehende Architektur

- **Datenfluss:** Hyperliquid Read-only APIs → `MarketContextCollector` → `CoinMarketContext` → `confluence_score.v1` → `market_confluence_latest.json` → v77-Paper-Gate.
- **CoinGecko ist bereits angebunden** in `src/market/fundamentals.py` und wird durch `src/tools/market_confluence_report.py` geladen.
- CoinGecko-Daten erscheinen im normalisierten Snapshot, **beeinflussen den Confluence-Score aber noch nicht**.
- Hyperliquid liefert Funding, Premium, OI, L2-Tiefe und Impact. `derivatives_history_collector.py` berechnet OI-/Funding-Deltas und einen einfachen `crowded_long_watch`.
- **DefiLlama und echte Liquidationsdaten sind im getrackten Code nicht integriert.**
- v77 liest den persistierten Confluence-Report über `_confluence_blockers()`, prüft dabei aber **weder Report-Alter noch Source-Freshness**.

### Kritische Lücken

1. **Source-Provenance**
   - Vorhanden sind nur freie `source`-Strings.
   - Es fehlen eindeutige `source_id`, Endpoint-/Schema-Version und `snapshot_id`.

2. **Freshness und Reliability**
   - CoinGecko hat weder `observed_at/collected_at` noch Alter, TTL oder Reliability.
   - Ein partieller CoinGecko-Response bleibt global `loaded`; aktuell fehlte beispielsweise HYPE im Report, ohne globalen Partial-Status.
   - Die Hyperliquid-Reliability bewertet nur Candle/L2-Verfügbarkeit, nicht externe Quellen.

3. **Fail-open beim v77-Confluence-Gate**
   - Fehlender Report → keine Blocker.
   - Fehlender Coin im Report → keine Blocker.
   - Alter Report → wird ungeprüft verwendet.
   - Nur syntaktisch ungültiger JSON-Report blockiert.

4. **Crowding**
   - v77-Features enthalten Funding/OI/Premium, aber `entry_blockers()` wertet diese nicht direkt aus.
   - Der separate OI-Historienkontext wird nicht in v77 eingespeist.
   - Der aktuelle Crowding-Detektor erkennt nur Long-Crowding, nicht symmetrisch Short-Crowding.

5. **Outcome-Attribution**
   - Trades tragen `data_window_id` und TradingView-Impulse.
   - Es fehlen die beim Einstieg tatsächlich verwendeten Confluence-/CoinGecko-/DefiLlama-/Crowding-Snapshots.
   - Exits und Promotion-Report können daher PnL nicht nach Datenquelle, Freshness oder Gate-Zustand auswerten.

## Minimale konkrete Integrationspunkte

### 1. Gemeinsamer Source-Envelope

Keine große Pipeline-Neufassung, sondern ein kleines gemeinsames Metadatenobjekt:

```json
{
  "source_id": "binance_usdm:global_long_short_ratio:v1",
  "snapshot_id": "sha256:...",
  "provider_observed_at": "...",
  "collected_at": "...",
  "age_seconds": 42,
  "max_age_seconds": 600,
  "status": "loaded|partial|missing|stale|error",
  "reliability": 0.80,
  "reliability_reasons": [],
  "blockers": []
}
```

Einbaupunkte:

- `src/market/fundamentals.py`
- neue kleine Adapter `src/market/defillama.py` und `src/market/crowding.py`
- `src/market/snapshot.py`
- `src/tools/market_confluence_report.py`

Initiale TTLs:

- CoinGecko: **15–30 Minuten**
- Binance/Bybit Crowding REST: **10 Minuten**
- Liquidationsstream: **30 Sekunden**
- DefiLlama TVL: **6 Stunden**

Bei aktiviertem externem Experiment müssen `missing`, `stale`, `partial_required_coin` und `low_reliability` explizite Blocker sein; die bestehende Baseline sollte unverändert weiterlaufen.

### 2. CoinGecko härten, nicht doppelt implementieren

In `fundamentals.py`:

- vorhandenen Client behalten;
- `source_id = coingecko:coins_markets:v3`;
- angeforderte gegen gelieferte IDs vergleichen;
- fehlende Coins als `partial` plus `coingecko_coin_missing:<COIN>`;
- `collected_at`, Alter, TTL und numerische Reliability ergänzen;
- CoinGecko zunächst nur für Universe-/Liquiditätsrisiko verwenden, **nicht als kurzfristigen Richtungsscore**.

### 3. DefiLlama als langsamen On-chain-Kontext

Empfohlene öffentliche Endpoints:

- `https://api.llama.fi/protocol/{slug}`
- `https://api.llama.fi/v2/chains`

Explizite Mapping-Tabelle statt Symbol-Heuristik:

- HYPE → Hyperliquid-Protokoll
- ENA → Ethena-Protokoll
- SOL/SUI → Chain-TVL, klar als Chain-Kontext markiert

Wichtig: LINK darf nicht einfach Ethereum-Chain-TVL zugeschrieben werden; das wäre keine LINK-spezifische Fundamentalmetrik.

Zunächst nur erfassen:

- `tvl_usd`
- Änderung zum vorherigen Snapshot
- Mapping-Typ `protocol|chain`
- Mapping-Version
- Freshness/Reliability

DefiLlama sollte anfangs **Research-/Attributionskontext**, kein harter intraday Directional-Score sein.

### 4. Kostenlose Crowding-/Liquidationsdaten

Ohne Secrets live verifiziert:

- Binance:
  - `globalLongShortAccountRatio`
  - `openInterest`
  - Funding/Premium
- Bybit:
  - `account-ratio`
  - `open-interest`

Für echte Liquidationen existieren kostenlose öffentliche WebSockets, z. B. Bybit `allLiquidation.{symbol}` mit 500-ms-Push. Öffentliche REST-Historie ist dagegen nicht verlässlich verfügbar.

Minimaler Ansatz:

- **Phase A ohne Prozessänderung:** Binance/Bybit REST-Ratios + bestehende Hyperliquid Funding/OI-Deltas.
- **Phase B separat:** Liquidations-WebSocket-Collector mit JSONL-Events und rollierenden 1m/5m/15m-Aggregaten. Erst anbinden, wenn Stream-Coverage und Freshness messbar sind.
- Keine erfundenen Nullwerte: Ohne Stream muss `liquidation_notional_usd=null` plus `liquidation_feed_missing` stehen.

Crowding sollte zunächst als symmetrischer Gate-Kontext arbeiten:

- `crowded_long`: Long-Ratio hoch + positives Funding + steigendes OI
- `crowded_short`: Short-Ratio hoch + negatives Funding + steigendes OI
- `liquidation_cascade`: starke Liquidationen + OI-Abbau

Ein einzelnes Venue-Signal nur niedrige/mittlere Reliability; höhere Reliability erst bei Binance/Bybit/Hyperliquid-Bestätigung.

### 5. v77-Gate fail-closed machen

Konkreter Punkt: `src/tools/v77_trend_retest_runtime.py::_confluence_blockers()`.

Bei aktiviertem External-Confluence-Modus blockieren:

- Report fehlt
- Coin fehlt
- Report oder erforderliche Quelle stale
- Reliability unter Schwelle
- erforderlicher `snapshot_id` fehlt

Keine stillen Fallbacks. CoinGecko/DefiLlama sollten zunächst nur im Shadow-Experiment verpflichtend sein, damit die v77-Baseline vergleichbar bleibt.

### 6. Outcome-Attribution

Beim Entry unveränderlich mitspeichern:

```json
{
  "context_snapshot_id": "...",
  "source_snapshot_ids": {
    "hyperliquid": "...",
    "coingecko": "...",
    "defillama": "...",
    "binance_crowding": "...",
    "bybit_crowding": "..."
  },
  "source_freshness": {},
  "source_reliability": {},
  "gate_decisions": [],
  "crowding_bucket": "neutral"
}
```

Diese Felder müssen von Signal → Position → Entry → Exit durchgereicht werden. `v77_promotion_report.py` kann anschließend PnL/PF und Blocker-Wirkung nach:

- Quellen-Coverage,
- Freshness-Bucket,
- Reliability-Bucket,
- Crowding-Zustand,
- Gate aktiv/inaktiv

auswerten. Das ist belastbare Outcome-Attribution, ohne Kausalität zu behaupten.

## Hinweis zum Repository-Zustand

Während der Read-only-Prüfung erschienen zwei **ungetrackte, offenbar parallel erzeugte Entwürfe**:

- `src/research/external_market_context.py`
- `src/tools/external_market_context_collect.py`

Sie wurden von mir weder erstellt noch verändert. Der Entwurf geht in die richtige Richtung, ist aber noch nicht integriert und hat u. a. keine Provider-Timestamps, keine numerische Reliability, keine per-source TTL, ein problematisches LINK→Ethereum-TVL-Mapping und keine Outcome-Attribution.

**Von mir erstellte oder geänderte Dateien: keine.**