feat(v10): Stablecoin Risk Radar defensive rotation overlay

NRI was offense-only through v9. v10 closes the loop:

- stablecoin_risk.py: 5-bucket SRR model
  (Peg+Flow+Reserves+Liquidity+Contagion), 15-stable universe
- backtest.py: SRR overlay, DEFENSIVE_ROTATION trigger when
  RISK_OFF + top conviction < 30
- live_demo.py: live CMC stable metrics, SRR ranking + target
  in JSON output
- 3 historical scenarios: BASELINE_2026, USDC_SVB_2023,
  UST_DEATH_2022 — all validate correct historical verdicts
- skill.yaml + README bumped to v10.0

Author: asbestos22

README.md

@@ -2,18 +2,31 @@
 
 [![python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
 [![chain](https://img.shields.io/badge/chain-BNB%20Chain%20%2B%20Multichain-F0B90B.svg)](https://www.bnbchain.org/)
-[![version](https://img.shields.io/badge/version-9.0-F0B90B.svg)](https://github.com/asbestos22/narrative-rotation-index)
+[![version](https://img.shields.io/badge/version-10.0-F0B90B.svg)](https://github.com/asbestos22/narrative-rotation-index)
 [![license](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 [![mcp](https://img.shields.io/badge/MCP-compatible-purple.svg)](https://modelcontextprotocol.io/)
 [![tests](https://github.com/asbestos22/narrative-rotation-index/actions/workflows/tests.yml/badge.svg)](https://github.com/asbestos22/narrative-rotation-index/actions/workflows/tests.yml)
 [![live](https://img.shields.io/badge/live-nri.realdo.org-F0B90B.svg)](https://nri.realdo.org/)
 
 A CMC-native AI-agent skill that ranks crypto narratives by relative strength, liquidity expansion, attention velocity, and macro regime — then outputs backtestable portfolio weights with structured confidence explanations and optional BNB Chain (BSC) Trust Wallet execution payloads.
 
+**v10.0** adds the **Stablecoin Risk Radar (SRR)** defensive rotation overlay: NRI scores narratives for offense, SRR scores stablecoins for defense. When regime flips RISK_OFF and top narrative conviction drops below 30, capital rotates to the safest-scoring stable.
+
 Built for the **CMC AI Agent Hub** with native **BNBAgent SDK** and **Trust Wallet Agent Kit** integration. Exposed as an **MCP server** so any MCP-aware client can call it.
 
 **Live dashboard:** [nri.realdo.org](https://nri.realdo.org/)
 
+## v10.0 — Stablecoin Risk Radar (defensive rotation)
+
+NRI was offense-only through v9. v10 closes the loop with a defensive layer:
+
+- **5-bucket SRR model:** `SRR = 0.30×Peg + 0.25×Flow + 0.20×Reserves + 0.15×Liquidity + 0.10×Contagion`
+- **9 live-tracked stables:** USDT, USDC, FDUSD, USDe, DAI, FRAX, TUSD, USDD, lisUSD (15-stable universe in `stablecoin_risk.py`, all BNB Hack-eligible)
+- **Verdict bands:** SAFE 0–25 · WATCH 26–50 · EXIT 51–75 · EMERGENCY 76–100
+- **Defensive trigger:** RISK_OFF regime + top narrative conviction < 30 → rotation to safest stable with BSC contract address surfaced
+- **Backtest scenarios:** BASELINE_2026 (calm), USDC_SVB_2023 (banking crisis), UST_DEATH_2022 (algorithmic stable collapse) — all validate historical accuracy
+- **Live overlay:** SRR pulls real CMC data on every refresh, scores all 9 stables, surfaces the rotation target on the dashboard
+
 ## v9.0 — Multichain Narrative Coverage
 
 - **10 narratives** (was 5): AI Tokens, AI Agents, RWA, DePIN, Meme, Privacy, DeFi Blue, L1/L2, Gaming/NFT, BNB Chain
@@ -29,6 +42,8 @@ Built for the **CMC AI Agent Hub** with native **BNBAgent SDK** and **Trust Wall
 $ python live_demo.py            # live CMC scoring
 $ python mcp_server.py           # MCP stdio server (Claude Desktop, CMC Hub, agents)
 $ python backtest.py             # 90-day historical basket simulation
+$ python stablecoin_risk.py      # SRR baseline scenario
+$ python stablecoin_risk.py USDC_SVB_2023   # historical depeg replay
 $ python -m unittest tests       # 15 unit tests
 ```
 
@@ -50,7 +65,7 @@ python live_demo.py
 
 ## What is NRI
 
-> A backtestable strategy skill that scans 10 crypto narratives, detects market regime, ranks by relative strength and liquidity expansion, penalizes crowded late-cycle moves, and outputs portfolio weights plus an optional BNB Chain (BSC) Trust Wallet execution payload.
+> A backtestable strategy skill that scans 10 crypto narratives + 9 stablecoins, detects market regime, ranks by relative strength and liquidity expansion, penalizes crowded late-cycle moves, scores stablecoin defensive rotation targets, and outputs portfolio weights plus an optional BNB Chain (BSC) Trust Wallet execution payload.
 
 ## Narrative Exhaustion Detector — The Original Moat
 

backtest.py

@@ -1059,6 +1059,40 @@ def global_scan(regime="TRANSITION"):
     else:
         rotation = f"DEFENSIVE — increase stablecoin allocation. Lowest: {bottom[0]}"
 
+    # ---- v10: Stablecoin Risk Radar (SRR) overlay ----
+    # NRI scores narratives for offense; SRR picks the safest defensive target.
+    # Trigger DEFENSIVE_ROTATION when regime is RISK_OFF or top conviction < 30.
+    try:
+        from stablecoin_risk import rank_stables, rotation_target, SCENARIOS
+        srr_scenario = "USDC_SVB_2023" if regime == "RISK_OFF" else "BASELINE_2026"
+        srr_scores = rank_stables(SCENARIOS[srr_scenario])
+        srr_target = rotation_target(srr_scores)
+        srr_payload = {
+            "scenario": srr_scenario,
+            "rankings": [
+                {"symbol": s.symbol, "verdict": s.verdict, "score": s.score,
+                 "issuer": s.issuer, "type": s.type}
+                for s in srr_scores
+            ],
+            "target": (
+                {"symbol": srr_target.symbol, "verdict": srr_target.verdict,
+                 "score": srr_target.score, "bsc_address":
+                 __import__("stablecoin_risk").STABLE_UNIVERSE.get(srr_target.symbol, {}).get("bsc")}
+                if srr_target else None
+            ),
+        }
+
+        # Defensive override: if regime is RISK_OFF AND top conviction < 30,
+        # rotate capital to safest stable (if any).
+        if regime == "RISK_OFF" and top[1]["conviction"] < 30 and srr_target:
+            rotation = (
+                f"DEFENSIVE_ROTATION → {srr_target.symbol} ({srr_target.verdict}, "
+                f"SRR {srr_target.score}). Top narrative {top[0]} conviction "
+                f"{top[1]['conviction']} below threshold."
+            )
+    except Exception as e:  # pragma: no cover — overlay must never break NRI
+        srr_payload = {"error": f"SRR overlay unavailable: {e}"}
+
     # Build risks list from bottom performers
     top_narrative = top[0]
     top_result = top[1]
@@ -1081,6 +1115,7 @@ def global_scan(regime="TRANSITION"):
         "top_verdict": top_result["verdict"],
         "top_conviction": top_result["conviction"],
         "risks": risks,
+        "stablecoin_risk": srr_payload,
     }
 
 
@@ -1294,7 +1329,7 @@ def run_backtest(narrative, days=90, initial_capital=10000.0):
 # ==============================================================================
 def main():
     print("=" * 80)
-    print("CMC Narrative Rotation Index (NRI) Skill v8.1")
+    print("CMC Narrative Rotation Index (NRI) Skill v10.0 — multichain + stablecoin risk radar")
     print("BNBAgent SDK + Trust Wallet Agent Kit + x402 + Kaito SoFi")
     print("=" * 80)
     time.sleep(0.2)
@@ -1395,7 +1430,7 @@ def main():
     sizing_pct = 5 * REGIME_SIZING[regime]
     confidence_output = {
         "skill": "narrative-rotation-index",
-        "version": "8.1",
+        "version": "10.0",
         "regime": regime,
         "top_narrative": top_n,
         "verdict": top_d["verdict"],
@@ -1461,7 +1496,7 @@ def main():
     print(f"\n{'='*80}")
     print("SUMMARY")
     print(f"{'='*80}")
-    print(f"  Skill:              CMC Narrative Rotation Index (NRI) v8.1")
+    print(f"  Skill:              CMC Narrative Rotation Index (NRI) v10.0")
     print(f"  Regime:             {regime} (cap: {cap}/100)")
     print(f"  Top Narrative:      {top_n} ({top_d['verdict']}, {top_d['conviction']}/{cap})")
     print(f"  Exhaustion:         {top_d['exhaustion_score']}/100")

live_demo.py

@@ -82,6 +82,42 @@ def fetch_fear_greed(api_key: str) -> int:
         return 50
 
 
+# ---------------------------------------------------------------------------
+# v10: Stablecoin Risk Radar — live metrics from CMC
+# ---------------------------------------------------------------------------
+STABLES_TO_TRACK = ["USDT", "USDC", "FDUSD", "USDe", "DAI", "FRAX", "TUSD", "USDD", "lisUSD"]
+
+
+def fetch_stable_metrics(api_key: str) -> list:
+    """Fetch live stablecoin metrics, return list[StableMetrics]."""
+    from stablecoin_risk import StableMetrics
+
+    try:
+        quotes = fetch_quotes(STABLES_TO_TRACK, api_key)
+    except RuntimeError:
+        return []
+
+    metrics = []
+    for sym in STABLES_TO_TRACK:
+        if sym not in quotes:
+            continue
+        v = quotes[sym]
+        q = (v[0] if isinstance(v, list) else v).get("quote", {}).get("USD", {})
+        price = q.get("price")
+        peg_pct = (price - 1.0) * 100 if price else None
+        metrics.append(StableMetrics(
+            symbol=sym,
+            peg_deviation_pct=peg_pct,
+            peg_deviation_24h_max_pct=peg_pct,  # CMC doesn't expose intraday max, use spot
+            market_cap_usd=q.get("market_cap"),
+            market_cap_change_7d_pct=q.get("percent_change_7d"),
+            market_cap_change_24h_pct=q.get("percent_change_24h"),
+            volume_24h_usd=q.get("volume_24h"),
+            volume_change_24h_pct=q.get("volume_change_24h"),
+        ))
+    return metrics
+
+
 def transform_to_scoring_schema(
     narrative: str,
     quotes: dict[str, Any],
@@ -310,6 +346,56 @@ def run_live(narrative: str | None, output_json: bool) -> int:
 
         output["narratives"][n] = narrative_out
 
+    # ---- v10: Stablecoin Risk Radar overlay ----
+    try:
+        from stablecoin_risk import rank_stables, rotation_target, STABLE_UNIVERSE
+        live_stables = fetch_stable_metrics(api_key) if api_key else []
+        if live_stables:
+            srr_scores = rank_stables(live_stables)
+            srr_target = rotation_target(srr_scores)
+            output["stablecoin_risk"] = {
+                "source": "cmc_live",
+                "rankings": [
+                    {
+                        "symbol": s.symbol,
+                        "verdict": s.verdict,
+                        "score": s.score,
+                        "issuer": s.issuer,
+                        "type": s.type,
+                        "bucket_scores": s.bucket_scores,
+                        "reasons": s.reasons[:3],
+                        "risks": s.risks[:3],
+                        "bsc_address": STABLE_UNIVERSE.get(s.symbol, {}).get("bsc"),
+                    }
+                    for s in srr_scores
+                ],
+                "target": (
+                    {
+                        "symbol": srr_target.symbol,
+                        "verdict": srr_target.verdict,
+                        "score": srr_target.score,
+                        "bsc_address": STABLE_UNIVERSE.get(srr_target.symbol, {}).get("bsc"),
+                    }
+                    if srr_target else None
+                ),
+            }
+
+            # Defensive rotation override on the macro signal
+            top_score = max(
+                (d["conviction"] for d in output["narratives"].values()),
+                default=0,
+            )
+            if regime == "RISK_OFF" and top_score < 30 and srr_target:
+                output["macro"]["defensive_rotation"] = {
+                    "trigger": "RISK_OFF + top conviction < 30",
+                    "target_symbol": srr_target.symbol,
+                    "target_verdict": srr_target.verdict,
+                    "target_score": srr_target.score,
+                    "target_bsc_address": STABLE_UNIVERSE.get(srr_target.symbol, {}).get("bsc"),
+                }
+    except Exception as e:
+        output["stablecoin_risk"] = {"error": str(e)}
+
     if output_json:
         print(json.dumps(output, indent=2))
     else:

skill.yaml

@@ -1,16 +1,19 @@
 name: narrative-rotation-index
-version: "9.0"
+version: "10.0"
 description: >
   A CMC-native Narrative Rotation Index (NRI) skill with multichain narrative coverage
-  aligned to the BNB Hack 149-token whitelist. Dynamic token discovery, Kaito (SoFi)
-  social intelligence, 5-bucket scoring, narrative exhaustion detection, auto-execute
-  toggle, and optional Trust Wallet execution payloads. v9.0: 10 narratives, 48 curated
-  tokens with verified BSC contracts (Binance-Peg BEP-20 wrappers for ETH/SOL-native).
+  aligned to the BNB Hack 149-token whitelist + Stablecoin Risk Radar (SRR) defensive
+  rotation overlay. NRI scores narratives for offense; SRR scores stablecoins for defense.
+  When regime flips RISK_OFF and top narrative conviction < 30, capital rotates to the
+  safest-scoring stable. v10.0: 10 narratives + 9 stablecoins, dual 5-bucket model,
+  defensive rotation triggers, historical depeg backtests (USDC SVB 2023, UST 2022).
 author: ASBESTOS19
 tags:
   - narrative-rotation
   - regime-detection
   - exhaustion-detector
+  - stablecoin-risk-radar
+  - defensive-rotation
   - quant-strategy
   - x402-enforced
   - bnbagent-sdk
@@ -31,6 +34,19 @@ supported_narratives:
   - Gaming/NFT   # AXS, SAND, MANA, GALA, IMX
   - BNB Chain    # BNB, CAKE, BAKE, XVS, ALPACA
 
+stablecoin_risk_radar:
+  description: >
+    Defensive rotation overlay. SRR_score = 0.30×Peg + 0.25×Flow + 0.20×Reserves
+    + 0.15×Liquidity + 0.10×Contagion. Verdicts: SAFE 0-25, WATCH 26-50, EXIT 51-75,
+    EMERGENCY 76-100. Trigger: RISK_OFF regime + top narrative conviction < 30 →
+    rotate to safest-scoring stable.
+  coverage:
+    - USDT, USDC, FDUSD, USD1, USDe, DAI, FRAX, FRXUSD, TUSD, USDD, lisUSD, USDF, EURI, XUSD, FF
+  backtest_scenarios:
+    - BASELINE_2026
+    - USDC_SVB_2023
+    - UST_DEATH_2022
+
 scoring_model:
   description: >
     5-bucket weighted scoring with narrative-specific fundamental customization.