@senpi/runtime 3.0.0-dev.openclaw-upgrade-mai.20260623210452 → 3.0.0-dev.runtime-phase-2.20260623210537

package/examples/scanners-multi-strategy.mjs

@@ -0,0 +1,165 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  createScannerRuntimeModule,
+  momentumScanner,
+  prescreenerScanner,
+} from "../dist/scanners/index.js";
+
+function createInstruments() {
+  return [
+    {
+      name: "BTC",
+      isDelisted: false,
+      maxLeverage: 10,
+      context: {
+        markPx: 104,
+        prevDayPx: 100,
+        midPx: 104,
+        dayNtlVlm: 70_000_000,
+        openInterest: 2_000_000_000,
+        funding: 0.001,
+      },
+    },
+    {
+      name: "ETH",
+      isDelisted: false,
+      maxLeverage: 8,
+      context: {
+        markPx: 102.5,
+        prevDayPx: 100,
+        midPx: 102.5,
+        dayNtlVlm: 50_000_000,
+        openInterest: 1_200_000_000,
+        funding: 0.001,
+      },
+    },
+  ];
+}
+
+function createCandles() {
+  return {
+    BTC: {
+      candles: {
+        "1h": [
+          {
+            timestamp: 1,
+            open: 100,
+            high: 102,
+            low: 99,
+            close: 100,
+            volume: 1200,
+          },
+          {
+            timestamp: 2,
+            open: 100,
+            high: 105,
+            low: 100,
+            close: 104,
+            volume: 1400,
+          },
+        ],
+      },
+    },
+    ETH: {
+      candles: {
+        "1h": [
+          {
+            timestamp: 1,
+            open: 100,
+            high: 101,
+            low: 99,
+            close: 100,
+            volume: 900,
+          },
+          {
+            timestamp: 2,
+            open: 100,
+            high: 103,
+            low: 100,
+            close: 102.5,
+            volume: 1100,
+          },
+        ],
+      },
+    },
+  };
+}
+
+async function main() {
+  const stateDir = await mkdtemp(join(tmpdir(), "scanners-example-multi-"));
+
+  const module = createScannerRuntimeModule({
+    stateDir,
+    scanners: [prescreenerScanner, momentumScanner],
+    strategies: [
+      {
+        id: "alpha",
+        name: "Alpha",
+        scannerOverrides: {
+          momentum: {
+            config: {
+              timeframe: "1h",
+              minMovePct: 3.5,
+              maxCandidates: 10,
+              minDayVolume: 1_000_000,
+              minSignalScore: 0.2,
+              requirePrescreened: true,
+            },
+          },
+        },
+      },
+      {
+        id: "beta",
+        name: "Beta",
+        scannerOverrides: {
+          momentum: {
+            config: {
+              timeframe: "1h",
+              minMovePct: 1.5,
+              maxCandidates: 10,
+              minDayVolume: 1_000_000,
+              minSignalScore: 0.2,
+              requirePrescreened: true,
+            },
+          },
+        },
+      },
+    ],
+    providers: {
+      getInstruments: async () => createInstruments(),
+      getCandles: async () => createCandles(),
+    },
+  });
+
+  try {
+    await module.runOnce("alpha", "prescreener");
+    await module.runOnce("beta", "prescreener");
+
+    const alphaMomentum = await module.runOnce("alpha", "momentum");
+    const betaMomentum = await module.runOnce("beta", "momentum");
+
+    const alphaSignals = await module.querySignals({
+      strategyId: "alpha",
+      scannerId: "momentum",
+    });
+    const betaSignals = await module.querySignals({
+      strategyId: "beta",
+      scannerId: "momentum",
+    });
+
+    console.log("multi-strategy: alpha momentum signals =", alphaMomentum.signals.length);
+    console.log("multi-strategy: beta momentum signals =", betaMomentum.signals.length);
+    console.log("multi-strategy: alpha queried signals =", alphaSignals.length);
+    console.log("multi-strategy: beta queried signals =", betaSignals.length);
+  } finally {
+    await module.stop();
+    await rm(stateDir, { recursive: true, force: true });
+  }
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/examples/scanners-position-tracker-e2e.mjs

@@ -0,0 +1,225 @@
+/**
+ * Position-tracker E2E example — connects to the real Senpi MCP server,
+ * fetches clearing house state for a strategy wallet, and runs the
+ * position-tracker scanner to detect open positions and deltas.
+ *
+ * Runs 3 iterations to showcase the full lifecycle:
+ *   1. First run — all current positions appear as POSITION_OPENED deltas.
+ *   2. Second run — no deltas (positions unchanged between scans).
+ *   3. Third run — same as second (steady-state heartbeat).
+ *
+ * Requires environment variables:
+ *
+ *   export SENPI_API_KEY="your-api-key"
+ *   export SENPI_MCP_URL="https://mcp.prod.senpi.ai/mcp"
+ *
+ * Optionally set STRATEGY_ADDRESS to override the default wallet:
+ *
+ *   export STRATEGY_ADDRESS="0x..."
+ *
+ * Usage:
+ *
+ *   npm run build
+ *   node examples/scanners-position-tracker-e2e.mjs
+ */
+
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import {
+  createScannerRuntimeModule,
+  createSenpiScannerProviders,
+  positionTrackerScanner,
+} from "../dist/scanners/index.js";
+
+// ─── Env guard ──────────────────────────────────────────────────────────────
+
+const SENPI_API_KEY = process.env.SENPI_API_KEY;
+const SENPI_MCP_URL = process.env.SENPI_MCP_URL;
+const STRATEGY_ADDRESS =
+  process.env.STRATEGY_ADDRESS;
+
+if (!SENPI_API_KEY || !SENPI_MCP_URL || !STRATEGY_ADDRESS) {
+  console.error(
+    "Missing required env vars. Set SENPI_API_KEY, SENPI_MCP_URL, and STRATEGY_ADDRESS before running.\n" +
+    "  export SENPI_API_KEY='your-api-key'\n" +
+    "  export SENPI_MCP_URL='https://mcp.prod.senpi.ai/mcp'\n" +
+    "  export STRATEGY_ADDRESS='0x...'",
+  );
+  process.exit(1);
+}
+
+// ─── MCP → SenpiToolClient bridge ──────────────────────────────────────────
+
+function createSenpiToolClient(mcpClient) {
+  return {
+    async callTool(name, args) {
+      const result = await mcpClient.callTool({ name, arguments: args });
+
+      if (result.isError) {
+        const errorText =
+          Array.isArray(result.content) &&
+            result.content.length > 0 &&
+            result.content[0].type === "text"
+            ? result.content[0].text
+            : JSON.stringify(result.content);
+        throw new Error(`MCP tool "${name}" returned error: ${errorText}`);
+      }
+
+      if (result.structuredContent !== undefined) {
+        return result.structuredContent;
+      }
+
+      if (Array.isArray(result.content) && result.content.length > 0) {
+        const first = result.content[0];
+        if (first.type === "text") {
+          try {
+            return JSON.parse(first.text);
+          } catch {
+            return first.text;
+          }
+        }
+      }
+
+      return result.content;
+    },
+  };
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+function printPositionSnapshot(snapshot, indent = "    ") {
+  console.log(
+    `${indent}${snapshot.direction} ${snapshot.asset} on ${snapshot.dex}`,
+  );
+  console.log(
+    `${indent}  size: ${snapshot.size}  entry: $${snapshot.entryPrice}  leverage: ${snapshot.leverage}x (${snapshot.leverageType})`,
+  );
+  console.log(
+    `${indent}  margin: $${snapshot.margin.toFixed(2)}  liqPrice: ${snapshot.liquidationPrice != null ? "$" + snapshot.liquidationPrice.toFixed(2) : "n/a"}`,
+  );
+  console.log(
+    `${indent}  uPnL: $${snapshot.unrealizedPnl.toFixed(4)}  ROE: ${snapshot.roe.toFixed(2)}%`,
+  );
+}
+
+function printDelta(signal) {
+  const meta = signal.meta || {};
+  console.log(
+    `  [${signal.signalType}] ${meta.positionKey}  sizeDelta=${meta.sizeDelta}`,
+  );
+  if (meta.current) {
+    printPositionSnapshot(meta.current);
+  }
+}
+
+// ─── Main ───────────────────────────────────────────────────────────────────
+
+async function main() {
+  // 1. Connect to MCP.
+  console.log("Connecting to", SENPI_MCP_URL, "...");
+  const transport = new StreamableHTTPClientTransport(new URL(SENPI_MCP_URL), {
+    requestInit: {
+      headers: { Authorization: `Bearer ${SENPI_API_KEY}` },
+    },
+  });
+  const mcpClient = new Client({
+    name: "position-tracker-e2e",
+    version: "0.0.1",
+  });
+  await mcpClient.connect(transport);
+  console.log("Connected.\n");
+
+  // 2. Create providers backed by the real MCP client.
+  const providers = createSenpiScannerProviders({
+    client: createSenpiToolClient(mcpClient),
+    logLevel: "warn",
+    cacheTtlMs: { instruments: 0, smData: 0, candles: 0 },
+    retries: 2,
+  });
+
+  // 3. Create the scanner runtime module with position-tracker only.
+  const stateDir = await mkdtemp(join(tmpdir(), "position-tracker-e2e-"));
+  const mod = createScannerRuntimeModule({
+    stateDir,
+    scanners: [positionTrackerScanner],
+    strategies: [{ id: STRATEGY_ADDRESS, name: "E2E Position Tracker" }],
+    providers,
+  });
+
+  try {
+    console.log(`Strategy address: ${STRATEGY_ADDRESS}\n`);
+
+    // ── Run 1: first scan — all positions appear as POSITION_OPENED ─────
+    console.log("── Run 1 (initial scan) ──");
+    const run1 = await mod.runOnce(STRATEGY_ADDRESS, "position-tracker");
+    console.log("  status:", run1.status);
+    console.log("  positionCount:", run1.summary?.positionCount ?? 0);
+    console.log("  deltaCount:", run1.summary?.deltaCount ?? 0);
+    console.log("  signals:", run1.signals.length);
+    if (run1.signals.length > 0) {
+      console.log("\n  Deltas:");
+      for (const sig of run1.signals) {
+        printDelta(sig);
+      }
+    }
+    console.log();
+
+    // ── Run 2: second scan — should be steady state (no deltas) ─────────
+    console.log("── Run 2 (steady state) ──");
+    const run2 = await mod.runOnce(STRATEGY_ADDRESS, "position-tracker");
+    console.log("  status:", run2.status);
+    console.log("  positionCount:", run2.summary?.positionCount ?? 0);
+    console.log("  deltaCount:", run2.summary?.deltaCount ?? 0);
+    console.log("  signals:", run2.signals.length);
+    if (run2.signals.length > 0) {
+      console.log("\n  Unexpected deltas:");
+      for (const sig of run2.signals) {
+        printDelta(sig);
+      }
+    } else {
+      console.log("  (no deltas — positions unchanged, as expected)");
+    }
+    console.log();
+
+    // ── Run 3: third scan — still steady state ──────────────────────────
+    console.log("── Run 3 (steady state) ──");
+    const run3 = await mod.runOnce(STRATEGY_ADDRESS, "position-tracker");
+    console.log("  status:", run3.status);
+    console.log("  positionCount:", run3.summary?.positionCount ?? 0);
+    console.log("  deltaCount:", run3.summary?.deltaCount ?? 0);
+    console.log("  signals:", run3.signals.length);
+    if (run3.signals.length > 0) {
+      console.log("\n  Unexpected deltas:");
+      for (const sig of run3.signals) {
+        printDelta(sig);
+      }
+    } else {
+      console.log("  (no deltas — positions unchanged, as expected)");
+    }
+    console.log();
+
+    // ── Query all persisted signals ─────────────────────────────────────
+    const allSignals = await mod.querySignals({
+      strategyId: STRATEGY_ADDRESS,
+    });
+    console.log("── Persisted signals ──");
+    console.log("  total:", allSignals.length);
+    for (const sig of allSignals) {
+      console.log(
+        `    [${sig.scannerId}] ${sig.signalType} ${sig.asset} (${sig.direction})`,
+      );
+    }
+  } finally {
+    await mod.stop();
+    await transport.close();
+    await rm(stateDir, { recursive: true, force: true });
+  }
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/examples/scanners-scheduled-events.mjs

@@ -0,0 +1,96 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  createScannerRuntimeModule,
+  buildCompositionFromScanners,
+  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,
+    ...buildCompositionFromScanners([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);
+});