@senpi/trading-runtime 1.0.0

package/examples/scanners-scheduled-events.mjs

@@ -0,0 +1,95 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  createScannerRuntimeModule,
+  oiTrackerScanner,
+} from "../dist/scanners/index.js";
+
+function createInstruments() {
+  return [
+    {
+      name: "BTC",
+      isDelisted: false,
+      maxLeverage: 10,
+      context: {
+        markPx: 100,
+        prevDayPx: 99,
+        midPx: 100,
+        dayNtlVlm: 60_000_000,
+        openInterest: 2_200_000_000,
+        funding: 0.001,
+      },
+    },
+  ];
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function main() {
+  const stateDir = await mkdtemp(join(tmpdir(), "scanners-example-scheduled-"));
+  const events = {
+    start: 0,
+    complete: 0,
+    skip: 0,
+    error: 0,
+  };
+
+  const module = createScannerRuntimeModule({
+    stateDir,
+    scanners: [oiTrackerScanner],
+    strategies: [
+      {
+        id: "alpha",
+        name: "Alpha",
+        scannerOverrides: {
+          "oi-tracker": {
+            intervalSeconds: 1,
+            config: {
+              minDayVolume: 1_000_000,
+              maxHistory: 5,
+            },
+          },
+        },
+      },
+    ],
+    providers: {
+      getInstruments: async () => createInstruments(),
+    },
+  });
+
+  module.on("scanner:run:start", () => {
+    events.start += 1;
+  });
+  module.on("scanner:run:complete", () => {
+    events.complete += 1;
+  });
+  module.on("scanner:run:skip", () => {
+    events.skip += 1;
+  });
+  module.on("scanner:run:error", () => {
+    events.error += 1;
+  });
+
+  try {
+    await module.start();
+    await sleep(2200);
+    await module.stop();
+    await sleep(100);
+
+    console.log("scheduled-events: start =", events.start);
+    console.log("scheduled-events: complete =", events.complete);
+    console.log("scheduled-events: skip =", events.skip);
+    console.log("scheduled-events: error =", events.error);
+  } finally {
+    await module.stop();
+    await rm(stateDir, { recursive: true, force: true });
+  }
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

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/trading-runtime
+   ```
+
+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 engine reference
+- `senpi guide schema` — full YAML schema

package/examples/strategies/dsl-showcase.yaml

@@ -0,0 +1,62 @@
+# 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 (default 30)
+  interval_seconds: 30
+  dsl_presets:
+    default:
+      # phase1 — fixed floor from entry. Floor = entry × (1 − max_loss_pct/100)
+      phase1:
+        enabled: true
+        # max_loss_pct — exit if price drops this % below entry
+        max_loss_pct: 4.0
+        # consecutive_breaches_required — ticks below floor before exit fires
+        consecutive_breaches_required: 3
+      # 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 — default % below HWM to trigger exit
+        retrace_threshold: 1.5
+        consecutive_breaches_required: 1
+        # tiers — trigger_pct = gain from entry that activates tier;
+        #         lock_pct = floor locked at entry × (1 + lock_pct%);
+        #         retrace = overrides retrace_threshold for this tier
+        tiers:
+          - { trigger_pct: 10, lock_pct: 5 }
+          - { trigger_pct: 20, lock_pct: 14 }
+          - { trigger_pct: 30, lock_pct: 22, retrace: 1.2 }
+          - { trigger_pct: 50, lock_pct: 40, retrace: 1.0 }
+          - { trigger_pct: 75, lock_pct: 60, retrace: 0.8 }
+          - { trigger_pct: 100, lock_pct: 80, retrace: 0.6 }

package/examples/strategies/fox.yaml

@@ -0,0 +1,55 @@
+name: fox
+version: 1.0.0
+description: OI-driven — prescreener + oi_tracker, no_decision entries.
+
+strategies:
+  fox:
+    wallet: "${WALLET_ADDRESS}"
+    budget: 1500
+    slots: 3
+    margin_per_slot: 400
+    trading_risk: moderate
+    enabled: true
+
+scanners:
+  - name: prescreener
+    type: prescreener
+    interval: 5m
+    config:
+      topN: 30
+      minDayVolume: 1000000
+      minLeverage: 2
+      minOpenInterest: 0
+  - name: oi_tracker
+    type: oi_tracker
+    interval: 2m
+    config:
+      minDayVolume: 1000000
+      maxHistory: 60
+
+actions:
+  - name: open_oi
+    action_type: OPEN_POSITION
+    decision_mode: no_decision
+    scanners: [oi_tracker]
+    min_confidence: 0
+
+exit:
+  engine: dsl
+  interval_seconds: 30
+  dsl_presets:
+    default:
+      phase1:
+        enabled: true
+        max_loss_pct: 2.5
+        consecutive_breaches_required: 3
+      phase2_trigger_tier: 0
+      phase2:
+        enabled: true
+        retrace_threshold: 1.2
+        consecutive_breaches_required: 1
+        tiers:
+          - { trigger_pct: 8, lock_pct: 4 }
+          - { trigger_pct: 15, lock_pct: 10 }
+          - { trigger_pct: 25, lock_pct: 18, retrace: 1.0 }
+          - { trigger_pct: 40, lock_pct: 28, retrace: 0.8 }

package/examples/strategies/minimal.yaml

@@ -0,0 +1,41 @@
+name: minimal
+version: 1.0.0
+description: Watch-only strategy — logs signals, opens no positions.
+
+strategies:
+  watch-only:
+    wallet: "${WALLET_ADDRESS}"
+    budget: "0"
+    slots: 1
+    margin_per_slot: 0
+    trading_risk: conservative
+    enabled: true
+
+scanners:
+  - name: emerging_movers
+    type: emerging_movers
+    interval: 60s
+    config:
+      topN: 20
+      minRankJump: 5
+      minScansBeforeSignals: 2
+
+actions:
+  - name: log_signals
+    action_type: OPEN_POSITION
+    decision_mode: no_decision
+    scanners: [emerging_movers]
+    min_confidence: 0
+
+exit:
+  engine: dsl
+  interval_seconds: 60
+  dsl_presets:
+    default:
+      phase1:
+        enabled: true
+        consecutive_breaches_required: 3
+        max_loss_pct: 5.0
+      phase2_trigger_tier: 0
+      phase2:
+        enabled: false