@senpi/trading-recipe 1.0.21

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-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);
+});