skill.yaml

name: narrative-rotation-index
version: "10.0"
description: >
  A CMC-native Narrative Rotation Index (NRI) skill with multichain narrative coverage
  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
  - trust-wallet-agent-kit
  - cmc-agent-hub
  - multichain
  - bnb-hack-eligible

supported_narratives:
  - AI Tokens    # FET, RENDER, TAO, AKT, NEAR, ICP
  - AI Agents    # VIRTUAL, AI16Z, FARTCOIN, GRIFFAIN, ZEREBRO
  - RWA          # ONDO, MKR, ENA, USUAL, PENDLE
  - DePIN        # FIL, RNDR, IOTX, AKT, GRT, THETA
  - Meme         # DOGE, SHIB, PEPE, WIF, BONK, FLOKI, PENGU
  - Privacy      # ZEC, XMR, ROSE, DASH
  - DeFi Blue    # AAVE, UNI, CAKE, COMP, CRV, SUSHI
  - L1/L2        # ETH, SOL, AVAX, ATOM, DOT, NEAR
  - 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

bnb_ai_agent_sdk:
  description: >
    NRI is registered as a discoverable on-chain agent on BSC mainnet via the
    real bnbagent SDK (pip install bnbagent). Any BSC client can resolve the
    agentId against the ERC-8004 registry to discover NRI's MCP and signal
    endpoints without an out-of-band registry.
  protocol: ERC-8004
  network: bsc-mainnet
  chain_id: 56
  agent_id: 129156
  agent_wallet: "0x7D93a5a96f9306E9b0D3B185aef702d03D1572C1"
  registry_contract: "0x8004A169FB4a3325136EB29fA0ceB6D2e539a432"
  transaction_hash: "0xcc86de3451e1623655f3f4c3b96ef453953191633bdbf088fb70e2c4b656c66d"
  block_number: 102791231
  gas_paid_bnb: 0
  paymaster: "MegaFuel (gas sponsored)"
  bscscan_tx: "https://bscscan.com/tx/0xcc86de3451e1623655f3f4c3b96ef453953191633bdbf088fb70e2c4b656c66d"
  bscscan_token: "https://bscscan.com/token/0x8004A169FB4a3325136EB29fA0ceB6D2e539a432?a=129156"
  agent_endpoints:
    - name: MCP
      endpoint: "https://nri.realdo.org/mcp"
      capabilities: [scan_narratives, score_narrative, detect_regime, rank_stables, rotation_target]
    - name: x402-signal-api
      endpoint: "https://nri.realdo.org/signal"
      capabilities: [full_scan, regime_update, stablecoin_risk]
  reproducibility:
    sdk_install: "pip install bnbagent"
    register_command: "python bnb_agent_integration.py --register"
    snapshot_file: "agent_identity.json"
  x402_paywall:
    enabled: true
    endpoint: "https://nri.realdo.org/signal"
    manifest: "https://nri.realdo.org/.well-known/x402"
    payment_token: "0xcE24439F2D9C6a2289F741120FE202248B666666"
    network: "eip155:56"
    pay_to: "0x7D93a5a96f9306E9b0D3B185aef702d03D1572C1"
    tiers:
      base: "0.01 U"
      regime_update: "0.1 U"
      full_scan: "0.5 U"
    buyer_demo: "python x402_buyer.py --tier base --url https://nri.realdo.org/signal"
    seller_module: "web/x402_paywall.py"
    verification:
      - signature_recovery
      - amount_check
      - recipient_check
      - asset_check
      - nonce_replay_protection_10min
      - validity_window_check
  erc8183_commerce:
    enabled: true
    description: "Sell signed NRI scans via on-chain escrow + optimistic settlement"
    service_price_base_units: 1000000000000000000
    service_price_human: "1 U"
    deliverable: "Full snapshot manifest with regime + 10 narratives + SRR overlay"
    deliverable_url: "https://nri.realdo.org/api/live"
    manifest_hash_algo: "keccak256(canonical_json)"
    lifecycle:
      - "client.createJob(provider=NRI, evaluator=router, expired_at, description)"
      - "client.registerJob(jobId, policy=optimistic)"
      - "client.setBudget(jobId, price)"
      - "client.fund(jobId, price)  # escrow locks U"
      - "provider.submit(jobId, manifest_hash, opt_params)"
      - "WAIT dispute_window"
      - "router.settle(jobId)  # escrow → provider on happy path"
    module: "erc8183_commerce.py"
    dry_run: "python erc8183_commerce.py"
    live_testnet: "python erc8183_commerce.py --live-testnet"
    proof_artifact: "erc8183_dryrun.json"

scoring_model:
  description: >
    5-bucket weighted scoring with narrative-specific fundamental customization.
  formula: "Final = 0.30×Momentum + 0.25×Liquidity + 0.20×Attention + 0.15×Fundamental + 0.10×Risk"
  buckets:
    Momentum (30%):
      - basket_return_7d_pct          # CMC-native
      - relative_strength_vs_btc_7d   # CMC-native
      - drawdown_from_30d_high_pct    # CMC-native
      - rsi_14                        # CMC-native
    Liquidity (25%):
      - volume_change_7d_pct          # CMC-native
      - market_cap_change_7d_pct      # CMC-native
      - liquidity_usd                 # CMC-native
      - spread_pct                    # CMC-native
    Attention (20%):
      - trending_rank_avg             # CMC-native
      - social_volume_24h             # Kaito (SoFi) mindshare + CMC community
      - kaito_mindshare_surge         # Kaito CT-wide attention spike detection
      - institutional_mentions_7d     # CMC news feed keyword filter
    Fundamental (15%):
      narrative-specific metrics — see alpha_metrics_by_narrative
    Risk Adjustment (10%):
      - volatility_30d                # CMC-native
      - exhaustion_score              # computed by exhaustion detector

alpha_metrics_by_narrative:
  AI Tokens:
    CMC-native: [basket_return_7d, volume_change_7d, market_cap_change_7d, trending_rank, volatility_30d, relative_strength_vs_btc, rsi_14]
    External:
      - metric: github_commits_7d
        source: "GitHub API, organization repos"
      - metric: developer_growth_30d_pct
        source: "GitHub API, unique contributors"
      - metric: partnership_announcements_7d
        source: "CMC news feed keyword filter"
  RWA:
    CMC-native: [basket_return_7d, volume_change_7d, market_cap_change_7d, trending_rank, volatility_30d, rsi_14]
    External:
      - metric: tvl_change_7d_pct
        source: "DeFiLlama API"
      - metric: institutional_mentions_7d
        source: "CMC news sentiment, 'institutional' keyword"
      - metric: regulatory_clarity_score
        source: "CMC news sentiment, 'regulation'+'SEC' keyword, normalized 1-10"
      - metric: yield_premium_vs_treasuries_bps
        source: "DeFiLlama yield API vs FRED 10y treasury"
  DePIN:
    CMC-native: [basket_return_7d, volume_change_7d, market_cap_change_7d, trending_rank, volatility_30d, rsi_14]
    External:
      - metric: active_nodes_7d_growth_pct
        source: "Protocol dashboards"
      - metric: revenue_per_node_usd
        source: "Protocol dashboards"
      - metric: network_utilization_pct
        source: "Protocol dashboards"
  Meme:
    CMC-native: [basket_return_7d, volume_change_7d, market_cap_change_7d, trending_rank, volatility_30d, rsi_14]
    External:
      - metric: social_volume_24h
        source: "LunarCrush / CMC community stats"
      - metric: holder_growth_7d_pct
        source: "On-chain (BSCScan holders endpoint)"
      - metric: dev_sell_pressure
        source: "On-chain team wallet → CEX transfers, < $50k/7d = Low"
      - metric: whale_accumulation_7d_usd
        source: "On-chain whale wallet tracking"
  Privacy:
    CMC-native: [basket_return_7d, volume_change_7d, market_cap_change_7d, trending_rank, volatility_30d, rsi_14]
    External:
      - metric: mixer_volume_7d_usd
        source: "On-chain mixer contract analysis"
      - metric: regulatory_risk_score
        source: "Inverse CMC news sentiment, 'regulation'+'privacy', normalized 1-10"
      - metric: shielded_pool_growth_7d_pct
        source: "Protocol dashboards"

actions:
  - name: GLOBAL_SCAN
    description: >
      Cross-narrative rotation engine. Evaluates all 5 narratives using 4-bucket scoring,
      ranks by conviction, applies quadratic portfolio weighting, and detects market regime.
      Outputs rotation signal: CONCENTRATE / BALANCED / DEFENSIVE.
    inputs:
      - name: risk_profile
        type: string
        enum: ["Conservative", "Balanced", "Aggressive"]
    outputs:
      - name: regime
        type: string
        enum: ["RISK_ON", "RISK_OFF", "TRANSITION"]
      - name: narrative_rankings
        type: array
        description: "All 5 narratives ranked by conviction with bucket scores and exhaustion"
      - name: portfolio_weights
        type: object
        description: "Quadratic-weighted allocation (w_i = conv_i^2 / sum), min threshold 20, max 35% per narrative"
      - name: rotation_signal
        type: string

  - name: RUN_SKILL
    description: >
      Single-narrative deep dive with structured confidence output. Returns verdict,
      conviction score, bucket breakdown, top reasons, risk factors, execution guardrail
      check, and optional TWAK payload.
    inputs:
      - name: narrative
        type: string
        enum: ["AI Tokens", "RWA", "DePIN", "Meme", "Privacy"]
    outputs:
      - name: verdict
        type: string
        enum: ["STRONG_LONG", "LONG", "NEUTRAL", "AVOID"]
      - name: conviction
        type: integer
        description: "0-100, capped by regime (RISK_ON=100, TRANSITION=75, RISK_OFF=50)"
      - name: bucket_scores
        type: object
        description: "Individual scores for momentum, liquidity, attention, fundamental, risk"
      - name: exhaustion_score
        type: integer
        description: "0-100: 0-30 healthy, 31-60 caution, 61-100 crowded/late-cycle"
      - name: reasons
        type: array
        items: string
        description: "Top factors driving the conviction score"
      - name: risks
        type: array
        items: string
        description: "Factors that could invalidate the signal"
      - name: execution_guardrails
        type: object
        description: "Slippage, allocation, liquidity, spread, and token age checks"
      - name: twak_payload
        type: object
        description: "Optional BNBAgent SDK v1 ToolCall, gated behind user confirmation"

  - name: DETECT_REGIME
    description: >
      Classifies market regime from Fear & Greed, BTC dominance, and mcap momentum.
      Uses Markov chain (70% stay probability) for persistence.
    inputs:
      - name: fear_greed_index
        type: integer
      - name: btc_dominance_pct
        type: number
      - name: total_mcap_change_7d
        type: number
    outputs:
      - name: regime
        type: string
      - name: conviction_cap
        type: integer
      - name: position_multiplier
        type: number

exhaustion_detector:
  description: >
    Penalizes late-cycle, overcrowded narrative entries. Checks for parabolic returns
    with declining volume, social hype without holder growth, near-high with falling
    volume, extreme volatility, and crowd consensus crowding.
  score_ranges:
    - "0-30: Healthy trend — full conviction allowed"
    - "31-60: Caution — sizing reduced"
    - "61-100: Crowded/late-cycle — strong penalty, sizing heavily reduced"

execution_guardrails:
  max_slippage_large_cap_pct: 1.0
  max_slippage_meme_pct: 2.5
  max_allocation_per_narrative_pct: 35.0
  max_allocation_per_token_pct: 15.0
  min_liquidity_usd: 500000
  max_spread_pct: 1.5
  min_token_age_days: 7
  requires_user_confirmation: false

risk_controls:
  circuit_breaker:
    threshold_pct: 15
    action: "All signals → NEUTRAL, sizing → 10% until recovery to 5% drawdown"
  conviction_decay:
    rate_pct_per_day: 10
    description: "Conviction decays 10%/day without signal refresh. Requires recurring x402 calls."

execution_routing:
  framework: "bnbagent-sdk"
  target_wallet: "trust-wallet-agent-kit"
  description: >
    Autonomous execution-ready output. Generates v1 ToolCall payloads that
    execute without user confirmation through the configured wallet agent.

x402_integration:
  enabled: true
  pricing_model: "tiered"
  tiers:
    base: {fee_usd: 0.05, description: "Standard signal call"}
    regime_update: {fee_usd: 0.20, description: "Real-time regime classification"}
    full_scan: {fee_usd: 0.50, description: "5-narrative scan with execution payload"}
  enforcement: "strict"

backtest_config:
  engine: "historical-basket-simulation"
  initial_capital: 10000
  default_period_days: 90
  distribution: "Student's t (df=3)"
  regime_model: "Markov chain (70% persistence)"
  trade_costs:
    swap_fee_pct: 0.1
    slippage_pct: 0.1
  rebalance_frequency: "event-driven"
  position_size_base_pct: 5.0
  metrics_tracked:
    - total_return
    - max_drawdown
    - sharpe_ratio
    - sortino_ratio
    - calmar_ratio
    - win_rate
    - profit_factor
    - total_fees_paid

dynamic_token_discovery:
  description: >
    Scans CMC trending + new listings for new launch candidates that could
    outperform core basket tokens. Especially high-turnover for Meme narrative.
  sources:
    - "CMC /v1/cryptocurrency/trending"
    - "CMC /v1/cryptocurrency/new"
    - "Kaito mindshare endpoint (CT-wide viral detection)"
  filters:
    min_age_days: 3
    max_age_days: 30
    min_volume_24h: 5000000
    max_cmc_rank: 200
  behavior: >
    New launches are listed separately from core basket tokens. They pass through
    the same scoring pipeline but carry a 'new_launch' flag so the agent knows
    these are higher-risk, higher-reward additions. Especially active for Meme
    narrative where token turnover is highest.

kaito_integration:
  description: >
    Kaito (SoFi) provides Crypto Twitter-wide social intelligence.
    Unlike CMC community stats (on-platform only), Kaito scans ALL of CT
    for mindshare, mentions, engagement, and viral signals.
  data_points:
    - kaito_mindshare_score: "Normalized 0-100, measures CT-wide narrative attention"
    - kaito_mindshare_surge: "Boolean, true when mindshare spikes >2x in 48h"
    - social_volume_24h: "Aggregated from Kaito + CMC community stats"
  use_in_scoring: "Attention bucket (+15 for mindshare surge, +10 for social surge on new launches)"

auto_execute:
  description: >
    Autonomous TWAK payload generation. Payloads are generated with
    `requires_user_confirmation: false` so the configured wallet agent
    executes them without a manual confirmation step.
    NOTE: This skill generates v1 ToolCall payloads; final signing and
    broadcast are performed by the downstream wallet/agent infrastructure
    the payload is routed to.
  default: true
  config_location: "AUTO_EXECUTE flag at top of backtest.py"
  when_to_enable: "Enabled by default for autonomous agents with pre-approved risk parameters"
  when_to_disable: "For manual trading, testing, or first-time setup"

example_call:
  action: RUN_SKILL
  input:
    narrative: "AI Tokens"
    risk_profile: "Balanced"
  x402_header:
    X-PAYMENT: "<base64(JSON) EIP-3009 TransferWithAuthorization — see build_x402_payment()>"
    X-Tier: "full_scan"
  output:
    skill: "narrative-rotation-index"
    version: "10.0"
    regime: "TRANSITION"
    top_narrative: "Meme"
    verdict: "STRONG_LONG"
    conviction: 74
    cap: 75
    position_size: "3.0%"
    rotation_signal: "CONCENTRATE_MEME (conviction 74/75)"
    exhaustion: "25/100"
    bucket_scores:
      momentum: 70
      liquidity: 85
      attention: 55
      fundamental: 60
      risk_adjustment: 70
    reasons:
      - "Strong relative strength vs BTC (1.215x)"
      - "Healthy 7d return (+21.5%)"
      - "RSI approaching oversold (38.5)"
      - "Volume expanding rapidly (85% WoW)"
      - "Market cap expanding (19% WoW)"
      - "Deep liquidity ($85M)"
    risks:
      - "Regime is TRANSITION — not full risk-on, allocation reduced"
      - "If Meme volume drops below 20d average, signal downgrades to LONG"
    execution_guardrails:
      execution_allowed: true
      violations: []
    twak_payload:
      bnbagent_sdk_format: "v1"
      action: "trust_wallet_agent_kit.multi_swap"
      narrative: "Meme"
      total_amount_usd: 500
      per_token_amount_usd: 166.67
      requires_user_confirmation: true