@senpi/trading-runtime 1.0.0

package/examples/scanners-emerging-movers-v4.mjs

@@ -0,0 +1,285 @@
+/**
+ * Emerging-movers v4 — signal detection showcase
+ *
+ * Demonstrates the five signal types detected by the emerging-movers scanner
+ * using a simulated 50-token SM leaderboard that evolves over 4 scans:
+ *
+ *   Scan 1: baseline (warm-up, no signals emitted)
+ *   Scan 2: FIRST_JUMP (WIF rockets from #45 to #3),
+ *           CONTRIB_EXPLOSION (ONDO goes 4x contribution),
+ *           NEW_ENTRY_DEEP (PENDLE appears at #8)
+ *   Scan 3: IMMEDIATE_MOVER (JUP jumps 15 ranks from #28),
+ *           DEEP_CLIMBER (RENDER climbs 6 ranks from #32)
+ *   Scan 4: climb streak + multi-scan climbing for tokens that kept improving
+ *
+ * Run:
+ *   npm run build && node examples/scanners-emerging-movers-v4.mjs
+ */
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  createScannerRuntimeModule,
+  emergingMoversScanner,
+} from "../dist/scanners/index.js";
+
+// ─── Simulated SM leaderboard ───────────────────────────────────────────────
+// 50 tokens with realistic contribution and trader distributions. Specific
+// tokens are manipulated across scans to trigger each v4 signal type.
+
+function makeBaseLeaderboard() {
+  const tokens = [
+    "BTC", "ETH", "SOL", "DOGE", "PEPE", "AVAX", "LINK", "MATIC",
+    "ARB", "OP", "SUI", "APT", "INJ", "TIA", "SEI", "NEAR",
+    "FTM", "ATOM", "DOT", "ADA", "XRP", "BNB", "UNI", "AAVE",
+    "MKR", "LDO", "CRV", "SNX", "COMP", "ONDO", "WIF", "JUP",
+    "RENDER", "FET", "RNDR", "PYTH", "JTO", "STRK", "MANTA", "DYM",
+    "PIXEL", "PORTAL", "ETHFI", "W", "ENA", "BOME", "SLERF", "MEW",
+    "MYRO", "BONK",
+  ];
+
+  return tokens.map((token, i) => ({
+    token,
+    direction: "up",
+    // Contribution decreases roughly linearly; top tokens dominate
+    pctOfTopTradersGain: Math.max(0.001, 0.50 - i * 0.009),
+    traderCount: Math.max(10, 500 - i * 8),
+    tokenPriceChangePct4h: Math.max(-2, 8 - i * 0.3),
+  }));
+}
+
+/** Scan 1: Baseline snapshot. Scanner warms up (no signals emitted). */
+function scan1() {
+  return makeBaseLeaderboard();
+}
+
+/**
+ * Scan 2: Three dramatic events.
+ * - WIF (was #31, contrib 0.230) rockets to massive contribution → lands ~#3
+ * - ONDO (was #30, contrib 0.239) goes 4x contribution → CONTRIB_EXPLOSION
+ * - PENDLE (new token, wasn't in scan 1) appears with high contribution → NEW_ENTRY_DEEP
+ */
+function scan2() {
+  const board = makeBaseLeaderboard();
+
+  // WIF: was at index 30 (rank ~31). Boost contribution so it sorts to ~rank 3.
+  // Also: WIF was ranked 31 (>= firstJumpMinPrevRank=30), triggering FIRST_JUMP.
+  const wif = board.find((m) => m.token === "WIF");
+  wif.pctOfTopTradersGain = 0.48;
+  wif.traderCount = 420;
+  wif.tokenPriceChangePct4h = 15.2;
+
+  // ONDO: was at index 29 (rank ~30). 4x its contribution for CONTRIB_EXPLOSION.
+  const ondo = board.find((m) => m.token === "ONDO");
+  ondo.pctOfTopTradersGain = ondo.pctOfTopTradersGain * 4.5;
+  ondo.traderCount = 310;
+  ondo.tokenPriceChangePct4h = 9.1;
+
+  // JUP: boost in scan 2 so it lands ~rank 26–29 (between deepClimbRankThreshold
+  // and firstJumpMinPrevRank). This sets up scan 3's IMMEDIATE_MOVER — prevRank
+  // will be >= 25 (qualifies as deep) but < 30 (not deep enough for FIRST_JUMP).
+  const jup = board.find((m) => m.token === "JUP");
+  jup.pctOfTopTradersGain = 0.28;
+  jup.traderCount = 260;
+
+  // PENDLE: replace a low-ranked filler token so PENDLE appears fresh.
+  const pendle = board.findIndex((m) => m.token === "BONK");
+  board[pendle] = {
+    token: "PENDLE",
+    direction: "up",
+    pctOfTopTradersGain: 0.42,
+    traderCount: 280,
+    tokenPriceChangePct4h: 7.8,
+  };
+
+  return board;
+}
+
+/**
+ * Scan 3: Rank-based signals.
+ * - JUP jumps 15+ ranks from ~#27 → IMMEDIATE_MOVER (not FIRST_JUMP because prevRank < 30)
+ * - RENDER climbs 6 ranks from deep → DEEP_CLIMBER
+ * - PENDLE continues climbing slightly (building streak history)
+ */
+function scan3() {
+  const board = makeBaseLeaderboard();
+
+  // Keep WIF high (now a returning token, not a first jump)
+  const wif = board.find((m) => m.token === "WIF");
+  wif.pctOfTopTradersGain = 0.46;
+  wif.traderCount = 400;
+
+  // ONDO settles back a bit (no longer 4x, so no explosion this scan)
+  const ondo = board.find((m) => m.token === "ONDO");
+  ondo.pctOfTopTradersGain = 0.35;
+
+  // PENDLE still present, climbing a bit
+  const pendle = board.findIndex((m) => m.token === "BONK");
+  board[pendle] = {
+    token: "PENDLE",
+    direction: "up",
+    pctOfTopTradersGain: 0.43,
+    traderCount: 290,
+    tokenPriceChangePct4h: 6.5,
+  };
+
+  // In scan 2, JUP was at its default position (index 31, contrib ~0.221).
+  // After sorting in scan 2 (with WIF and ONDO boosted), JUP lands around rank ~27.
+  // Here we give JUP a contribution that sorts it to ~rank 10, a jump of 15+.
+  // prevRank ~27 is >= deepClimbRankThreshold (25) but < firstJumpMinPrevRank (30),
+  // so it qualifies as IMMEDIATE_MOVER, not FIRST_JUMP.
+  const jup = board.find((m) => m.token === "JUP");
+  jup.pctOfTopTradersGain = 0.44;
+  jup.traderCount = 350;
+  jup.tokenPriceChangePct4h = 11.0;
+
+  // RENDER: was at index 32 (rank ~33). Moderate boost for DEEP_CLIMBER.
+  const render = board.find((m) => m.token === "RENDER");
+  render.pctOfTopTradersGain = 0.30;
+  render.traderCount = 240;
+  render.tokenPriceChangePct4h = 5.3;
+
+  return board;
+}
+
+/**
+ * Scan 4: Sustained climbing.
+ * - RENDER continues climbing → STREAK signal
+ * - PENDLE continues climbing → multi-scan CLIMBING detection
+ */
+function scan4() {
+  const board = makeBaseLeaderboard();
+
+  // WIF, ONDO, JUP remain high but stable
+  const wif = board.find((m) => m.token === "WIF");
+  wif.pctOfTopTradersGain = 0.45;
+  const ondo = board.find((m) => m.token === "ONDO");
+  ondo.pctOfTopTradersGain = 0.34;
+  const jup = board.find((m) => m.token === "JUP");
+  jup.pctOfTopTradersGain = 0.43;
+
+  // PENDLE keeps climbing
+  const pendle = board.findIndex((m) => m.token === "BONK");
+  board[pendle] = {
+    token: "PENDLE",
+    direction: "up",
+    pctOfTopTradersGain: 0.45,
+    traderCount: 310,
+    tokenPriceChangePct4h: 8.2,
+  };
+
+  // RENDER continues improving
+  const render = board.find((m) => m.token === "RENDER");
+  render.pctOfTopTradersGain = 0.36;
+  render.traderCount = 270;
+  render.tokenPriceChangePct4h = 6.8;
+
+  return board;
+}
+
+// ─── Main ───────────────────────────────────────────────────────────────────
+
+const SCAN_DATA = [scan1, scan2, scan3, scan4];
+
+async function main() {
+  const stateDir = await mkdtemp(join(tmpdir(), "emerging-movers-v4-"));
+  let scanIndex = 0;
+
+  const module = createScannerRuntimeModule({
+    stateDir,
+    scanners: [emergingMoversScanner],
+    strategies: [
+      {
+        id: "wolf",
+        name: "Wolf Strategy",
+        scannerOverrides: {
+          "emerging-movers": {
+            config: {
+              // Production-like v4 configuration
+              topN: 50,
+              minRankJump: 5,
+              minTopTradersGain: 0.01,
+              minScansBeforeSignals: 2,
+              historyLimit: 60,
+              immediateJumpThreshold: 10,
+              deepClimbRankThreshold: 25,
+              contribExplosionMultiplier: 3.0,
+              contribAccelThreshold: 0.003,
+              minVelocityForDeepClimber: 0.0003,
+              erraticReversalThreshold: 5,
+              climbStreakScans: 3,
+              rankClimbThreshold: 3,
+              newEntryDeepMaxRank: 20,
+              newEntryMaxRank: 35,
+              firstJumpMinPrevRank: 30,
+            },
+          },
+        },
+      },
+    ],
+    providers: {
+      getSmData: async () => {
+        const data = SCAN_DATA[scanIndex]();
+        scanIndex++;
+        return data;
+      },
+    },
+  });
+
+  try {
+    for (let i = 0; i < SCAN_DATA.length; i++) {
+      const result = await module.runOnce("wolf", "emerging-movers");
+      console.log(`\n── Scan ${i + 1} ──────────────────────────────────────`);
+      console.log(`Status: ${result.status} | Scanned: ${result.scannedCount} | Signals: ${result.signals.length}`);
+
+      if (result.signals.length === 0) {
+        console.log("(warm-up scan — no signals yet)");
+        continue;
+      }
+
+      for (const signal of result.signals) {
+        const m = signal.meta;
+        console.log(
+          `  [${signal.signalType}] ${signal.asset}`,
+          `| score=${signal.score}`,
+          `| rank=#${m.rank}`,
+          `| prev=#${m.prevRank ?? "new"}`,
+          `| jump=${m.jump}`,
+          `| vel=${m.contribVelocity}`,
+        );
+        console.log(`    reasons: ${(m.reasons).join(", ")}`);
+
+        const activeFactors = Object.entries(signal.factors)
+          .filter(([, v]) => v)
+          .map(([k]) => k);
+        if (activeFactors.length > 0) {
+          console.log(`    factors: ${activeFactors.join(", ")}`);
+        }
+      }
+
+      // Print summary breakdown
+      const bd = result.summary.signalBreakdown;
+      const counts = Object.entries(bd).filter(([, v]) => v > 0);
+      if (counts.length > 0) {
+        console.log(`  summary: ${counts.map(([k, v]) => `${k}=${v}`).join(", ")}`);
+      }
+    }
+
+    // Query all persisted signals
+    const allSignals = await module.querySignals({ strategyId: "wolf", limit: 50 });
+    console.log(`\n── Total persisted signals: ${allSignals.length} ──`);
+    const byType = {};
+    for (const s of allSignals) {
+      byType[s.signalType] = (byType[s.signalType] || 0) + 1;
+    }
+    console.log("By type:", byType);
+  } finally {
+    await module.stop();
+    await rm(stateDir, { recursive: true, force: true });
+  }
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

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