@senpi/runtime 3.0.0-dev.runtime-phase-2.20260623210537 → 3.0.0-dev.runtime-phase-2.20260625112547

package/examples/scanners-multi-strategy.mjs

@@ -1,165 +0,0 @@
-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

@@ -1,225 +0,0 @@
-/**
- * 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

@@ -1,96 +0,0 @@
-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

@@ -1,182 +0,0 @@
-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);
-});