@senpi/runtime 1.0.95-dev.20260408174401

package/examples/scanners-senpi-provider-client.mjs

@@ -0,0 +1,182 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  createScannerRuntimeModule,
+  createSenpiScannerProviders,
+  emergingMoversScanner,
+  momentumScanner,
+  prescreenerScanner,
+} from "../dist/scanners/index.js";
+
+function createMockSenpiToolClient() {
+  let smRun = 0;
+  return {
+    async callTool(name, args) {
+      if (name === "market_list_instruments") {
+        return {
+          success: true,
+          data: {
+            instruments: [
+              {
+                name: "BTC",
+                is_delisted: false,
+                max_leverage: 10,
+                context: {
+                  markPx: 106,
+                  prevDayPx: 100,
+                  midPx: 106,
+                  dayNtlVlm: 80_000_000,
+                  openInterest: 2_000_000_000,
+                  funding: 0.001,
+                },
+              },
+              {
+                name: "ETH",
+                is_delisted: false,
+                max_leverage: 8,
+                context: {
+                  markPx: 101,
+                  prevDayPx: 100,
+                  midPx: 101,
+                  dayNtlVlm: 40_000_000,
+                  openInterest: 1_000_000_000,
+                  funding: 0.001,
+                },
+              },
+            ],
+          },
+        };
+      }
+
+      if (name === "market_get_asset_data") {
+        if (args.asset === "BTC") {
+          return {
+            candles: {
+              "1h": [
+                { t: 1, o: 100, h: 102, l: 99, c: 100, v: 1000 },
+                { t: 2, o: 100, h: 107, l: 100, c: 106, v: 1400 },
+              ],
+            },
+          };
+        }
+        return {
+          candles: {
+            "1h": [
+              { t: 1, o: 100, h: 101, l: 99, c: 100, v: 900 },
+              { t: 2, o: 100, h: 101, l: 99, c: 100.4, v: 920 },
+            ],
+          },
+        };
+      }
+
+      if (name === "leaderboard_get_markets") {
+        smRun += 1;
+        const run1 = [
+          {
+            token: "SOL",
+            direction: "up",
+            pct_of_top_traders_gain: 0.16,
+            trader_count: 220,
+            token_price_change_pct_4h: 2.1,
+          },
+          {
+            token: "AVAX",
+            direction: "up",
+            pct_of_top_traders_gain: 0.18,
+            trader_count: 200,
+            token_price_change_pct_4h: 1.9,
+          },
+        ];
+        const run2 = [
+          {
+            token: "AVAX",
+            direction: "up",
+            pct_of_top_traders_gain: 0.17,
+            trader_count: 230,
+            token_price_change_pct_4h: 2.0,
+          },
+          {
+            token: "SOL",
+            direction: "up",
+            pct_of_top_traders_gain: 0.35,
+            trader_count: 250,
+            token_price_change_pct_4h: 4.2,
+          },
+        ];
+        return {
+          markets: {
+            markets: smRun === 1 ? run1 : run2,
+          },
+        };
+      }
+
+      throw new Error(`Unexpected tool call: ${name}`);
+    },
+  };
+}
+
+async function main() {
+  const stateDir = await mkdtemp(join(tmpdir(), "scanners-example-senpi-provider-"));
+  const toolClient = createMockSenpiToolClient();
+  const providers = createSenpiScannerProviders({
+    client: toolClient,
+    logLevel: "error",
+    maxCandleAssets: 10,
+    candleIntervals: ["1h"],
+    cacheTtlMs: {
+      smData: 0,
+    },
+  });
+
+  const module = createScannerRuntimeModule({
+    stateDir,
+    scanners: [prescreenerScanner, 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,
+  });
+
+  try {
+    await module.runOnce("alpha", "prescreener");
+    const momentum = await module.runOnce("alpha", "momentum");
+    await module.runOnce("alpha", "emerging-movers");
+    const emerging = await module.runOnce("alpha", "emerging-movers");
+
+    console.log("senpi-provider: momentum signals =", momentum.signals.length);
+    console.log("senpi-provider: emerging signals =", emerging.signals.length);
+  } finally {
+    await module.stop();
+    await rm(stateDir, { recursive: true, force: true });
+  }
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

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-ai/runtime
+   ```
+
+2. Copy a template and fill in your wallet:
+   ```bash
+   cp wolf.yaml my-recipe.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 recipe (hot-loads, no gateway restart):
+   ```bash
+   openclaw senpi runtime create -p my-recipe.yaml
+   ```
+
+5. Verify:
+   ```bash
+   openclaw senpi runtime 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,63 @@
+# 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.
+  Onchain position tracker — monitors the strategy wallet on Hyperliquid
+  for position lifecycle events (open, close, edit, flip) and wires them
+  into the DSL exit engine for automated trailing stop-loss management.
+
+
+notifications:
+  telegram_chat_id: "${TELEGRAM_CHAT_ID}"
+
+strategy:
+  wallet: "${WALLET_ADDRESS}"
+  budget: 500
+  slots: 2
+  margin_per_slot: 200
+  trading_risk: conservative
+  enabled: true
+
+# ── SCANNERS ──
+scanners:
+  - name: position_tracker
+    type: position_tracker
+    interval: 10s
+
+# ── ACTIONS ──
+actions:
+  - name: position_tracker_action
+    action_type: POSITION_TRACKER
+    decision_mode: rule
+    scanners: [position_tracker]
+
+exit:
+  engine: dsl
+  # interval_seconds — how often the price monitor runs
+  interval_seconds: 30
+  # dsl_preset — single exit profile (required for DslPlugin).
+  dsl_preset:
+    hard_timeout:
+      enabled: true
+      interval_in_minutes: 360
+    weak_peak_cut:
+      enabled: true
+      interval_in_minutes: 120
+      min_value: 5
+    dead_weight_cut:
+      enabled: true
+      interval_in_minutes: 5
+    phase1:
+      enabled: true
+      max_loss_pct: 4.0
+      retrace_threshold: 7
+      consecutive_breaches_required: 1
+    phase2:
+      enabled: true
+      tiers:
+        - { trigger_pct: 7,  lock_hw_pct: 40 }
+        - { trigger_pct: 12, lock_hw_pct: 55 }
+        - { trigger_pct: 15, lock_hw_pct: 75 }
+        - { trigger_pct: 20, lock_hw_pct: 85 }

package/examples/strategies/dsl.yaml

@@ -0,0 +1,47 @@
+name: position-tracker
+version: 1.0.0
+description: >
+  Onchain position tracker — monitors the strategy wallet on Hyperliquid
+  for position lifecycle events (open, close, edit, flip) and wires them
+  into the DSL exit engine for automated trailing stop-loss management.
+
+# ── STRATEGY ──
+# Minimal: only wallet address + optional fields (no budget/slots/margin needed)
+strategy:
+  wallet: "${WALLET_ADDRESS}"
+  enabled: true
+
+# ── SCANNERS ──
+scanners:
+  - name: position_tracker
+    type: position_tracker
+    interval: 10s
+
+# ── ACTIONS ──
+actions:
+  - name: position_tracker_action
+    action_type: POSITION_TRACKER
+    decision_mode: rule
+    scanners: [position_tracker]
+
+# ── EXIT (DSL) ──
+exit:
+  engine: dsl
+  interval_seconds: 30
+  dsl_preset:
+    phase1:
+      enabled: true
+      max_loss_pct: 3.0
+      retrace_threshold: 7
+      consecutive_breaches_required: 3
+    phase2:
+      enabled: true
+      tiers:
+        - { trigger_pct: 7,  lock_hw_pct: 40 }
+        - { trigger_pct: 12, lock_hw_pct: 55 }
+        - { trigger_pct: 15, lock_hw_pct: 75 }
+        - { trigger_pct: 20, lock_hw_pct: 85 }
+
+# ── NOTIFICATIONS ──
+notifications:
+  telegram_chat_id: "${TELEGRAM_CHAT_ID}"