@senpi/runtime 1.0.95-dev.20260408174401

package/examples/scanners-live-mcp.mjs

@@ -0,0 +1,208 @@
+/**
+ * Live MCP example — connects to the real Senpi MCP server and runs all
+ * four built-in scanners against live market data.
+ *
+ * Requires two environment variables:
+ *
+ *   export SENPI_API_KEY="your-api-key"
+ *   export SENPI_MCP_URL="https://mcp.prod.senpi.ai/mcp"
+ *   node examples/scanners-live-mcp.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,
+  prescreenerScanner,
+  oiTrackerScanner,
+  momentumScanner,
+  emergingMoversScanner,
+} 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;
+
+if (!SENPI_API_KEY || !SENPI_MCP_URL) {
+  console.error(
+    "Missing required env vars. Set SENPI_API_KEY and SENPI_MCP_URL before running.",
+  );
+  process.exit(1);
+}
+
+// ─── MCP → SenpiToolClient bridge ──────────────────────────────────────────
+
+/**
+ * Wraps the MCP SDK `Client` so it satisfies the `SenpiToolClient` interface
+ * expected by `createSenpiScannerProviders`.
+ *
+ * The MCP `callTool` returns `{ content: [{ type: "text", text: "…" }] }`.
+ * This bridge parses the JSON from the first text content item back into
+ * a plain object.
+ */
+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}`);
+      }
+
+      // Prefer structuredContent when available.
+      if (result.structuredContent !== undefined) {
+        return result.structuredContent;
+      }
+
+      // Fall back to parsing the first text content item.
+      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;
+    },
+  };
+}
+
+// ─── Main ───────────────────────────────────────────────────────────────────
+
+async function main() {
+  // 1. Connect to the Senpi MCP server.
+  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: "scanners-live-mcp", version: "0.0.1" });
+  await mcpClient.connect(transport);
+  console.log("Connected.\n");
+
+  // 2. Wire up scanner providers backed by the real MCP client.
+  const providers = createSenpiScannerProviders({
+    client: createSenpiToolClient(mcpClient),
+    logLevel: "info",
+    maxCandleAssets: 5,
+    candleIntervals: ["1h"],
+    cacheTtlMs: { instruments: 0, smData: 0, candles: 0 },
+    timeouts: {
+      marketListInstruments: 30_000,
+      marketGetAssetData: 30_000,
+      leaderboardGetMarkets: 30_000,
+    },
+    retries: 2,
+  });
+
+  // 3. Create the runtime module.
+  const stateDir = await mkdtemp(join(tmpdir(), "scanners-live-mcp-"));
+  const mod = createScannerRuntimeModule({
+    stateDir,
+    scanners: [prescreenerScanner, oiTrackerScanner, momentumScanner, emergingMoversScanner],
+    strategies: [
+      {
+        id: "live-demo",
+        name: "Live Demo",
+        scannerOverrides: {
+          momentum: {
+            config: {
+              timeframe: "1h",
+              minMovePct: 0.5,
+              maxCandidates: 5,
+              minDayVolume: 1_000_000,
+              minSignalScore: 0.1,
+              requirePrescreened: true,
+            },
+          },
+          "emerging-movers": {
+            config: {
+              topN: 10,
+              minRankJump: 1,
+              minTopTradersGain: 0.05,
+              minScansBeforeSignals: 2,
+              historyLimit: 30,
+            },
+          },
+        },
+      },
+    ],
+    providers,
+  });
+
+  try {
+    // 4. Run scanners in order.
+    console.log("── prescreener ──");
+    const prescreener = await mod.runOnce("live-demo", "prescreener");
+    console.log("  status:", prescreener.status);
+    console.log("  scanned:", prescreener.scannedCount);
+    console.log("  summary:", prescreener.summary);
+    console.log();
+
+    console.log("── oi-tracker ──");
+    const oiTracker = await mod.runOnce("live-demo", "oi-tracker");
+    console.log("  status:", oiTracker.status);
+    console.log("  scanned:", oiTracker.scannedCount);
+    console.log("  summary:", oiTracker.summary);
+    console.log();
+
+    console.log("── momentum ──");
+    const momentum = await mod.runOnce("live-demo", "momentum");
+    console.log("  status:", momentum.status);
+    console.log("  scanned:", momentum.scannedCount);
+    console.log("  signals:", momentum.signals.length);
+    for (const sig of momentum.signals) {
+      console.log(`    ${sig.direction} ${sig.asset}  score=${sig.score.toFixed(2)}  change=${sig.meta.changePct}%`);
+    }
+    console.log();
+
+    console.log("── emerging-movers (run 1 — warmup) ──");
+    const em1 = await mod.runOnce("live-demo", "emerging-movers");
+    console.log("  status:", em1.status);
+    console.log("  scanned:", em1.scannedCount);
+    console.log();
+
+    console.log("── emerging-movers (run 2 — can signal) ──");
+    const em2 = await mod.runOnce("live-demo", "emerging-movers");
+    console.log("  status:", em2.status);
+    console.log("  scanned:", em2.scannedCount);
+    console.log("  signals:", em2.signals.length);
+    for (const sig of em2.signals) {
+      console.log(`    ${sig.direction} ${sig.asset}  score=${sig.score.toFixed(2)}  jump=${sig.meta.jump}`);
+    }
+    console.log();
+
+    // 5. Query persisted signals across all scanners.
+    const allSignals = await mod.querySignals({ strategyId: "live-demo" });
+    console.log("── querySignals ──");
+    console.log("  total persisted:", allSignals.length);
+    for (const sig of allSignals) {
+      console.log(`    [${sig.scannerId}] ${sig.direction} ${sig.asset}  score=${sig.score.toFixed(2)}`);
+    }
+  } 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-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);
+});