@senpi/trading-recipe 1.0.21

package/examples/scanners-single-strategy.mjs

@@ -0,0 +1,198 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  createScannerRuntimeModule,
+  emergingMoversScanner,
+  momentumScanner,
+  oiTrackerScanner,
+  prescreenerScanner,
+} from "../dist/scanners/index.js";
+
+function createInstruments() {
+  return [
+    {
+      name: "BTC",
+      isDelisted: false,
+      maxLeverage: 10,
+      context: {
+        markPx: 106,
+        prevDayPx: 100,
+        midPx: 106,
+        dayNtlVlm: 80_000_000,
+        openInterest: 2_000_000_000,
+        funding: 0.001,
+      },
+    },
+    {
+      name: "ETH",
+      isDelisted: false,
+      maxLeverage: 8,
+      context: {
+        markPx: 101,
+        prevDayPx: 100,
+        midPx: 101,
+        dayNtlVlm: 40_000_000,
+        openInterest: 1_000_000_000,
+        funding: 0.001,
+      },
+    },
+  ];
+}
+
+function createCandles() {
+  return {
+    BTC: {
+      candles: {
+        "1h": [
+          {
+            timestamp: 1,
+            open: 100,
+            high: 102,
+            low: 99,
+            close: 100,
+            volume: 1000,
+          },
+          {
+            timestamp: 2,
+            open: 100,
+            high: 107,
+            low: 100,
+            close: 106,
+            volume: 1400,
+          },
+        ],
+      },
+    },
+    ETH: {
+      candles: {
+        "1h": [
+          {
+            timestamp: 1,
+            open: 100,
+            high: 101,
+            low: 99,
+            close: 100,
+            volume: 900,
+          },
+          {
+            timestamp: 2,
+            open: 100,
+            high: 101,
+            low: 99,
+            close: 100.4,
+            volume: 920,
+          },
+        ],
+      },
+    },
+  };
+}
+
+function createSmDataRun1() {
+  return [
+    {
+      token: "SOL",
+      direction: "up",
+      pctOfTopTradersGain: 0.18,
+      traderCount: 220,
+      tokenPriceChangePct4h: 2.1,
+    },
+    {
+      token: "AVAX",
+      direction: "up",
+      pctOfTopTradersGain: 0.16,
+      traderCount: 200,
+      tokenPriceChangePct4h: 1.9,
+    },
+  ];
+}
+
+function createSmDataRun2() {
+  return [
+    {
+      token: "AVAX",
+      direction: "up",
+      pctOfTopTradersGain: 0.17,
+      traderCount: 230,
+      tokenPriceChangePct4h: 2.0,
+    },
+    {
+      token: "SOL",
+      direction: "up",
+      pctOfTopTradersGain: 0.35,
+      traderCount: 250,
+      tokenPriceChangePct4h: 4.2,
+    },
+  ];
+}
+
+async function main() {
+  const stateDir = await mkdtemp(join(tmpdir(), "scanners-example-single-"));
+  let smDataRun = 0;
+
+  const module = createScannerRuntimeModule({
+    stateDir,
+    scanners: [prescreenerScanner, oiTrackerScanner, momentumScanner, emergingMoversScanner],
+    strategies: [
+      {
+        id: "alpha",
+        name: "Alpha",
+        scannerOverrides: {
+          momentum: {
+            config: {
+              timeframe: "1h",
+              minMovePct: 1.5,
+              maxCandidates: 10,
+              minDayVolume: 1_000_000,
+              minSignalScore: 0.2,
+              requirePrescreened: true,
+            },
+          },
+          "emerging-movers": {
+            config: {
+              topN: 10,
+              minRankJump: 1,
+              minTopTradersGain: 0.15,
+              minScansBeforeSignals: 2,
+              historyLimit: 30,
+            },
+          },
+        },
+      },
+    ],
+    providers: {
+      getInstruments: async () => createInstruments(),
+      getCandles: async () => createCandles(),
+      getSmData: async () => {
+        smDataRun += 1;
+        return smDataRun === 1 ? createSmDataRun1() : createSmDataRun2();
+      },
+    },
+  });
+
+  try {
+    await module.runOnce("alpha", "prescreener");
+    await module.runOnce("alpha", "oi-tracker");
+    const momentumResult = await module.runOnce("alpha", "momentum");
+    await module.runOnce("alpha", "emerging-movers");
+    const emergingResult = await module.runOnce("alpha", "emerging-movers");
+
+    const signals = await module.querySignals({
+      strategyId: "alpha",
+      limit: 20,
+    });
+
+    console.log("single-strategy: momentum signals =", momentumResult.signals.length);
+    console.log("single-strategy: emerging signals =", emergingResult.signals.length);
+    console.log("single-strategy: queried signals =", signals.length);
+  } finally {
+    await module.stop();
+    await rm(stateDir, { recursive: true, force: true });
+  }
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/examples/strategies/README.md

@@ -0,0 +1,45 @@
+# Strategy Templates
+
+| File | Style | Scanners | Decision | Use case |
+|------|-------|----------|----------|----------|
+| minimal.yaml | Watch-only | emerging_movers | no_decision | Verify setup; no positions |
+| wolf.yaml | Aggressive | emerging_movers | llm | Early entry on FIRST_JUMP |
+| viper.yaml | Moderate | prescreener + momentum | llm | Candle-based breakouts |
+| fox.yaml | OI-driven | prescreener + oi_tracker | no_decision | OI spike entries |
+| dsl-showcase.yaml | DSL reference | emerging_movers | no_decision | Annotated exit config |
+
+## Quickstart
+
+1. Install the plugin:
+   ```bash
+   openclaw plugins install @senpi/trading-recipe
+   ```
+
+2. Copy a template and fill in your wallet:
+   ```bash
+   cp wolf.yaml my-strategy.yaml
+   # edit: replace ${WALLET_ADDRESS}
+   ```
+
+3. Set environment variables:
+   ```bash
+   cp ../.env.example .env
+   # edit: SENPI_API_KEY, WALLET_ADDRESS
+   source .env
+   ```
+
+4. Load the strategy (hot-loads, no gateway restart):
+   ```bash
+   openclaw senpi trading-strategy create -p my-strategy.yaml
+   ```
+
+5. Verify:
+   ```bash
+   openclaw senpi trading-strategy list
+   ```
+
+## CLI reference
+
+- `senpi guide scanners` — scanner config fields
+- `senpi guide dsl` — DSL exit: phases, lock modes, tiers, time-based cuts
+- `senpi guide schema` — full YAML schema

package/examples/strategies/dsl-showcase.yaml

@@ -0,0 +1,60 @@
+# DSL showcase — every DSL field annotated for reference.
+# Use as a copy-paste reference when tuning exit behavior.
+name: dsl-showcase
+version: 1.0.0
+description: Annotated DSL exit config reference.
+
+strategies:
+  ref:
+    wallet: "${WALLET_ADDRESS}"
+    budget: 500
+    slots: 2
+    margin_per_slot: 200
+    trading_risk: conservative
+    enabled: true
+
+scanners:
+  - name: emerging_movers
+    type: emerging_movers
+    interval: 30s
+    config:
+      topN: 20
+      minRankJump: 5
+      minScansBeforeSignals: 2
+
+actions:
+  - name: open_ref
+    action_type: OPEN_POSITION
+    decision_mode: no_decision
+    scanners: [emerging_movers]
+    min_confidence: 0
+
+exit:
+  engine: dsl
+  # interval_seconds — how often the price monitor runs 
+  interval_seconds: 30
+  dsl_presets:
+    default:
+      # lock_mode: pctOfHighWater (default) = floor trails with high-water %; fixedRoe = fixed % of (entry→HW) per tier
+      lock_mode: pctOfHighWater
+      # phase1 — fixed floor from entry (max_loss_pct)
+      phase1:
+        enabled: true
+        # max_loss_pct — max loss % from entry (floor = entry × (1 − max_loss_pct/100/leverage) for LONG)
+        max_loss_pct: 4.0
+        # consecutive_breaches_required — ticks below floor before exit fires
+        consecutive_breaches_required: 1
+      # phase2_trigger_tier — 0 = phase2 starts when first tier is hit
+      phase2_trigger_tier: 0
+      # phase2 — trailing floor from high-water mark
+      phase2:
+        enabled: true
+        # retrace_threshold — ROE % below HWM for trailing floor (0.015 → 1.5%; engine divides by leverage)
+        retrace_threshold: 1.5
+        consecutive_breaches_required: 1
+        # tiers — trigger_pct = ROE % from entry that activates tier; lock_hw_pct = % of highWaterRoe to lock; breaches = per-tier override
+        tiers:
+          - { trigger_pct: 7,  lock_hw_pct: 40, breaches: 3 }
+          - { trigger_pct: 12, lock_hw_pct: 55, breaches: 2 }
+          - { trigger_pct: 15, lock_hw_pct: 75, breaches: 2 }
+          - { trigger_pct: 20, lock_hw_pct: 85, breaches: 1 }

package/examples/strategies/fox-minimal-loosened.yaml

@@ -0,0 +1,201 @@
+name: fox-minimal-loosened
+version: 1.6.0
+description: >
+  FOX v1.6 — loosened configuration for functional evaluation.
+  Scanner thresholds relaxed, LLM gauntlet simplified, and slots increased
+  to maximize signal volume. NOT for live trading.
+
+strategies:
+  fox-primary:
+    wallet: "${FOX_WALLET}"
+    budget: "3010"
+    slots: 3
+    margin_per_slot: 1000
+    trading_risk: aggressive
+    enabled: true
+
+scanners:
+  # ── Primary signal: emerging movers (every 60s, faster for eval) ──
+  - name: emerging_movers
+    type: emerging_movers
+    interval: 60s
+    blocked_assets: []
+    config:
+      topN: 100
+      minRankJump: 2
+      minTopTradersGain: 0.02
+      minScansBeforeSignals: 1
+      historyLimit: 60
+      immediateJumpThreshold: 5
+      deepClimbRankThreshold: 40
+      contribExplosionMultiplier: 1.5
+      contribAccelThreshold: 0.001
+      minVelocityForDeepClimber: 0.0001
+      erraticReversalThreshold: 10
+      climbStreakScans: 2
+      rankClimbThreshold: 2
+      firstJumpMinPrevRank: 15
+      minLeverage: 2
+      blacklist: []
+
+  # ── Macro context: BTC+ETH regime classification (every 4h) ──
+  - name: market_regime
+    type: market_regime
+    interval: 14400s
+    config:
+      btcWeight: 0.6
+      ethWeight: 0.4
+      emaFast: 9
+      emaSlow: 21
+      neutralThreshold: 0.3
+
+  # ── SM conviction reversal detection (every 5 min) ──
+  - name: sm_flip
+    type: sm_flip
+    interval: 300s
+    config:
+      minConviction: 4
+
+  # ── Margin safety net (every 5 min) ──
+  - name: watchdog
+    type: liquidation_watchdog
+    interval: 300s
+    config:
+      bufferWarningPct: 50
+      bufferCriticalPct: 30
+      liqDistanceWarningPct: 30
+      liqDistanceIsolatedWarningPct: 15
+      roeDangerPct: -15
+
+  # ── Infrastructure: prescreener for opportunity scanner (every 60s) ──
+  - name: prescreener
+    type: prescreener
+    interval: 60s
+    config:
+      topN: 50
+      minDayVolume: 200000
+      minLeverage: 2
+
+  # ── Secondary deep scan: 4-pillar opportunity scoring (every 10 min) ──
+  - name: opportunity
+    type: opportunity
+    interval: 600s
+    config:
+      minCompositeScore: 30
+      maxCandidates: 30
+      minDayVolume: 200000
+
+actions:
+  # ── Entry: LLM relaxed filter on emerging mover signals ──
+  - name: fox_entry
+    action_type: OPEN_POSITION
+    decision_mode: llm
+    decision_model: claude-sonnet-4-6
+    scanners: [emerging_movers]
+    min_confidence: 4
+    context:
+      - type: signal
+        value: emerging_movers
+      - type: market_regime
+        value: regime
+    decision_prompt: |
+      You are the FOX v1.6 entry filter in EVALUATION MODE. Evaluate emerging mover
+      signals with relaxed thresholds to maximize signal throughput for functional testing.
+
+      SIGNAL DATA:
+      {{emerging_movers}}
+
+      MARKET REGIME:
+      {{regime}}
+
+      ═══ LAYER 1: SIGNAL DETECTION (relaxed) ═══
+      - Must have at least one of: FIRST_JUMP, IMMEDIATE_MOVER, DEEP_CLIMBER, CONTRIB_EXPLOSION
+      - rankJumpThisScan ≥ 5 OR contribVelocity > 5
+      - Asset at #1-5 for 3+ scans → SKIP (move is over)
+
+      ═══ LAYER 2: SCORING (minimum 4 points) ═══
+      FIRST_JUMP:           +3
+      IMMEDIATE_MOVER:      +2
+      contribVelocity > 5:  +2
+      CONTRIB_EXPLOSION:    +2
+      DEEP_CLIMBER:         +1
+      RANK_UP:              +1
+      CLIMBING:             +1
+      ACCEL:                +1
+      STREAK:               +1
+      BTC 1h bias aligned:  +1
+
+      Minimum requirements: score ≥ 4, reasons ≥ 2, contribVelocity > 2
+
+      ═══ LAYER 3: VELOCITY & PRICE ACTION (relaxed) ═══
+      - Negative velocity without any jump reason → SKIP
+      - Any positive velocity is sufficient for all signal types
+      - Erratic rank history → SKIP only if no strong reason (FIRST_JUMP/CONTRIB_EXPLOSION)
+
+      ═══ LAYER 4: LEVERAGE & ASSET CHECKS (relaxed) ═══
+      - Max leverage for asset must be ≥ 2x
+      - XYZ equities: ignore trader count, use leverageType "ISOLATED" and dex "xyz"
+      - ≥ 5 SM traders required (crypto only, waived for XYZ)
+
+      ═══ LAYER 5: MARKET REGIME (relaxed) ═══
+      - BEARISH: prefer SHORT, but LONG allowed if score ≥ 6
+      - BULLISH: prefer LONG, but SHORT allowed if score ≥ 6
+      - NEUTRAL or stale: both directions allowed
+
+      ═══ ROTATION (slots full + new signal) ═══
+      - Weakest position has negative ROE → CUT and ENTER new
+      - Weakest has positive ROE or SM conviction 3+ → HOLD
+      - Never rotate positions younger than 5 minutes
+
+      ═══ ANTI-PATTERNS (hard blocks) ═══
+      - Rank #1-5 for 3+ scans → move is over
+      - Burned/blacklisted asset → SKIP
+
+      Respond:
+      {
+        "execute": true/false,
+        "actionType": "OPEN_POSITION",
+        "confidence": 1-10,
+        "reasoning": "one sentence",
+        "payload": {
+          "signals": [
+            { "asset": "<ticker>", "direction": "LONG" or "SHORT", "reason": "one sentence", "rotate_out": "<asset_to_cut>" }
+          ]
+        }
+      }
+
+  # ── SM flip: immediate close on conviction reversal ──
+  - name: sm_flip_close
+    action_type: CLOSE_POSITION
+    decision_mode: rule
+    scanners: [sm_flip]
+    min_confidence: 1
+
+  # ── Watchdog: emergency close on margin danger ──
+  - name: watchdog_close
+    action_type: CLOSE_POSITION
+    decision_mode: rule
+    scanners: [watchdog]
+    min_confidence: 1
+
+# ── DSL — trailing exit
+exit:
+  engine: dsl
+  interval_seconds: 30
+  dsl_presets:
+    with_phases:
+      lock_mode: pctOfHighWater
+      phase1:
+        enabled: true
+        max_loss_pct: 2.0
+        consecutive_breaches_required: 3
+      phase2_trigger_tier: 0
+      phase2:
+        enabled: true
+        retrace_threshold: 1.5
+        consecutive_breaches_required: 1
+        tiers:
+          - { trigger_pct: 7,  lock_hw_pct: 40, breaches: 3 }
+          - { trigger_pct: 12, lock_hw_pct: 55, breaches: 2 }
+          - { trigger_pct: 15, lock_hw_pct: 75, breaches: 2 }
+          - { trigger_pct: 20, lock_hw_pct: 85, breaches: 1 }

package/examples/strategies/fox-minimal.yaml

@@ -0,0 +1,209 @@
+name: fox-minimal
+version: 1.6.0
+description: >
+  FOX v1.6 — autonomous momentum trading via senpi-trading-recipe.
+  Emerging movers detect first jumps, LLM entry filter applies the five-layer
+  gauntlet, DSL v5.3.1 manages trailing exits, watchdog guards margin health,
+  market-regime provides macro context, sm-flip detects conviction reversals.
+
+strategies:
+  fox-primary:
+    wallet: "${FOX_WALLET}"
+    budget: "3010"
+    slots: 1
+    margin_per_slot: 1500
+    trading_risk: aggressive
+    enabled: true
+
+scanners:
+  # ── Primary signal: emerging movers (every 90s, matching Fox 3-min cron) ──
+  - name: emerging_movers
+    type: emerging_movers
+    interval: 90s
+    blocked_assets: []
+    config:
+      topN: 50
+      minRankJump: 5
+      minTopTradersGain: 0.1
+      minScansBeforeSignals: 2
+      historyLimit: 60
+      immediateJumpThreshold: 10
+      deepClimbRankThreshold: 25
+      contribExplosionMultiplier: 3
+      contribAccelThreshold: 0.003
+      minVelocityForDeepClimber: 0.0003
+      erraticReversalThreshold: 5
+      climbStreakScans: 3
+      rankClimbThreshold: 3
+      firstJumpMinPrevRank: 30
+      minLeverage: 7
+      blacklist: ["XPL", "kPEPE"]
+
+  # ── Macro context: BTC+ETH regime classification (every 4h) ──
+  - name: market_regime
+    type: market_regime
+    interval: 14400s
+    config:
+      btcWeight: 0.6
+      ethWeight: 0.4
+      emaFast: 9
+      emaSlow: 21
+      neutralThreshold: 0.3
+
+  # ── SM conviction reversal detection (every 5 min) ──
+  - name: sm_flip
+    type: sm_flip
+    interval: 300s
+    config:
+      minConviction: 4
+
+  # ── Margin safety net (every 5 min) ──
+  - name: watchdog
+    type: liquidation_watchdog
+    interval: 300s
+    config:
+      bufferWarningPct: 50
+      bufferCriticalPct: 30
+      liqDistanceWarningPct: 30
+      liqDistanceIsolatedWarningPct: 15
+      roeDangerPct: -15
+
+  # ── Infrastructure: prescreener for opportunity scanner (every 60s) ──
+  - name: prescreener
+    type: prescreener
+    interval: 60s
+    config:
+      topN: 30
+      minDayVolume: 500000
+      minLeverage: 2
+
+  # ── Secondary deep scan: 4-pillar opportunity scoring (every 15 min) ──
+  - name: opportunity
+    type: opportunity
+    interval: 900s
+    config:
+      minCompositeScore: 60
+      maxCandidates: 15
+      minDayVolume: 500000
+
+actions:
+  # ── Entry: LLM five-layer gauntlet on emerging mover signals ──
+  - name: fox_entry
+    action_type: OPEN_POSITION
+    decision_mode: llm
+    decision_model: claude-sonnet-4-6
+    scanners: [emerging_movers]
+    min_confidence: 7
+    context:
+      - type: signal
+        value: emerging_movers
+      - type: market_regime
+        value: regime
+    decision_prompt: |
+      You are the FOX v1.6 entry filter. Evaluate emerging mover signals through
+      a strict five-layer gauntlet. Speed is edge — enter on FIRST signal or skip.
+
+      SIGNAL DATA:
+      {{emerging_movers}}
+
+      MARKET REGIME:
+      {{regime}}
+
+      ═══ LAYER 1: FIRST JUMP DETECTION (mandatory) ═══
+      - Must have FIRST_JUMP reason (jumped 10+ ranks from #25+ in one scan)
+      - Previous rank must be ≥ 20 (outside top 20)
+      - rankJumpThisScan ≥ 15 OR contribVelocity > 15 (small jumps eliminated)
+      - Asset already at #1-10 for 2+ scans → SKIP (move is over)
+
+      ═══ LAYER 2: SCORING (minimum 7 points, 8 for NEUTRAL regime) ═══
+      FIRST_JUMP:           +3 (mandatory)
+      IMMEDIATE_MOVER:      +2
+      contribVelocity > 10: +2
+      CONTRIB_EXPLOSION:    +2
+      DEEP_CLIMBER:         +1
+      RANK_UP:              +1
+      CLIMBING:             +1
+      ACCEL:                +1
+      STREAK:               +1
+      BTC 1h bias aligned:  +1
+      UTC 04:00-13:59:      +1 (time-of-day bonus)
+      UTC 18:00-02:00:      -2 (evening penalty — needs score 9+ effective)
+
+      Minimum requirements: score ≥ 7, reasons ≥ 3, contribVelocity > 7 (hard gate)
+
+      ═══ LAYER 3: VELOCITY & PRICE ACTION ═══
+      - Negative velocity without big jump → SKIP
+      - IMMEDIATE_MOVER/FIRST_JUMP: vel > 0 sufficient
+      - DEEP_CLIMBER: vel ≥ 0.03% (0.0003 decimal)
+      - Erratic rank history (zigzag) → SKIP unless CONTRIB_EXPLOSION
+
+      ═══ LAYER 4: LEVERAGE & ASSET CHECKS ═══
+      - Max leverage for asset must be ≥ 7x — skip if capped at 3-5x
+      - XYZ equities: ignore trader count, require score ≥ 10,
+        use leverageType "ISOLATED" and dex "xyz"
+      - ≥ 10 SM traders required (crypto only, waived for XYZ)
+
+      ═══ LAYER 5: MARKET REGIME ═══
+      - BEARISH (bear ≥ 60, conf ≥ 50): SHORT only
+      - BULLISH (bull ≥ 60, conf ≥ 50): LONG only
+      - NEUTRAL or stale (> 1h): both directions if score ≥ 8
+
+      ═══ ROTATION (slots full + explosive FIRST_JUMP) ═══
+      - Weakest position has negative ROE → CUT and ENTER new
+      - Weakest has positive ROE or SM conviction 3+ → HOLD
+      - Never rotate positions younger than 10 minutes
+
+      ═══ ANTI-PATTERNS (hard blocks) ═══
+      - Rank #1-10 for 2+ scans → move is over
+      - 4+ reasons at rank #5 → already peaked
+      - Counter to BTC hourly trend → hard block
+      - Burned/blacklisted asset → SKIP
+
+      Respond:
+      {
+        "execute": true/false,
+        "actionType": "OPEN_POSITION",
+        "confidence": 1-10,
+        "reasoning": "one sentence",
+        "payload": {
+          "signals": [
+            { "asset": "<ticker>", "direction": "LONG" or "SHORT", "reason": "one sentence", "rotate_out": "<asset_to_cut>" }
+          ]
+        }
+      }
+
+  # ── SM flip: immediate close on conviction reversal ──
+  - name: sm_flip_close
+    action_type: CLOSE_POSITION
+    decision_mode: rule
+    scanners: [sm_flip]
+    min_confidence: 1
+
+  # ── Watchdog: emergency close on margin danger ──
+  - name: watchdog_close
+    action_type: CLOSE_POSITION
+    decision_mode: rule
+    scanners: [watchdog]
+    min_confidence: 1
+
+# ── DSL — trailing exit 
+exit:
+  engine: dsl
+  interval_seconds: 30
+  dsl_presets:
+    with_phases:
+      lock_mode: pctOfHighWater
+      phase1:
+        enabled: true
+        max_loss_pct: 2.0
+        consecutive_breaches_required: 3
+      phase2_trigger_tier: 0
+      phase2:
+        enabled: true
+        retrace_threshold: 1.5
+        consecutive_breaches_required: 1
+        tiers:
+          - { trigger_pct: 7,  lock_hw_pct: 40, breaches: 3 }
+          - { trigger_pct: 12, lock_hw_pct: 55, breaches: 2 }
+          - { trigger_pct: 15, lock_hw_pct: 75, breaches: 2 }
+          - { trigger_pct: 20, lock_hw_pct: 85, breaches: 1 }