@senpi/trading-runtime 1.0.0

package/dist/types/strategy.d.ts

@@ -0,0 +1,97 @@
+import type { CreatePositionRequest, CreatePositionResult, EditPositionResult } from "../senpi/types.js";
+/** Strategy configuration. Address is the strategy identifier (platform id). */
+export interface StrategyConfig {
+    address: string;
+    budget: number;
+    slots: number;
+    tradingRisk: string;
+    marginPerSlot?: number;
+    defaultLeverage?: number;
+    dailyLossLimit?: number;
+    dsl?: Record<string, unknown>;
+    guardRails?: Record<string, unknown>;
+    enabled?: boolean;
+}
+/** Account-level + position data from strategy_get_clearinghouse_state (single MCP call). */
+export interface ClearinghouseState {
+    accountValue: number;
+    totalMarginUsed: number;
+    totalUnrealizedPnl: number;
+    totalNtlPos: number;
+    withdrawable: number;
+    positions: OpenPosition[];
+}
+export interface OpenPosition {
+    coin: string;
+    dex: string;
+    szi: number;
+    entryPx: number;
+    leverage: number;
+    unrealizedPnl: number;
+    marginUsed: number;
+    liquidationPx: number | null;
+    returnOnEquity: number;
+}
+export interface PastTrade {
+    coin: string;
+    direction: 'LONG' | 'SHORT';
+    entryPx: number;
+    closePx: number;
+    szi: number;
+    realizedPnl: number;
+    closedTime: number;
+    openTime: number;
+    totalFees: number;
+}
+export interface OpenOrder {
+    orderId: number;
+    coin: string;
+    side: 'BUY' | 'SELL';
+    size: number;
+    price: number;
+    orderType: string;
+    status: string;
+    timestamp: number;
+}
+export interface StrategyDetails {
+    strategyId: string;
+    name: string;
+    status: string;
+    traderAddress: string;
+    initialBudget: number;
+    totalPnl: number;
+    pnlPercentage: number;
+    createdAt: string;
+}
+/** Runtime strategy state. Address is the strategy identifier and equals config.address. */
+export interface StrategyState {
+    readonly address: string;
+    readonly config: StrategyConfig;
+    getClearinghouseState(): ClearinghouseState | undefined;
+    getOpenPositions(): OpenPosition[] | undefined;
+    getPastTrades(): PastTrade[] | undefined;
+    getOpenOrders(): OpenOrder[] | undefined;
+    getAvailableSlots(): number;
+    getDetails(): StrategyDetails | undefined;
+    fetchClearinghouseState(): Promise<ClearinghouseState | undefined>;
+    fetchPastTrades(opts?: {
+        limit?: number;
+        offset?: number;
+        sort_by?: string;
+        sort_direction?: string;
+    }): Promise<PastTrade[] | undefined>;
+    fetchOpenOrders(): Promise<OpenOrder[] | undefined>;
+    fetchDetails(): Promise<StrategyDetails | undefined>;
+    refresh(): Promise<void>;
+    cancelOrder(orderId: number): Promise<unknown>;
+    closePosition(coin: string, reason: string, dex?: string): Promise<unknown>;
+    createPosition(params: CreatePositionRequest): Promise<CreatePositionResult>;
+    editPosition(payload: {
+        coin: string;
+        dex?: string;
+        stopLoss?: {
+            triggerPx: number;
+        };
+    }): Promise<EditPositionResult>;
+}
+//# sourceMappingURL=strategy.d.ts.map

package/dist/types/strategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"strategy.d.ts","sourceRoot":"","sources":["../../src/types/strategy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAIzG,gFAAgF;AAChF,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAID,6FAA6F;AAC7F,MAAM,WAAW,kBAAkB;IACjC,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,YAAY,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,KAAK,GAAG,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;CACnB;AAID,4FAA4F;AAC5F,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAGhC,qBAAqB,IAAI,kBAAkB,GAAG,SAAS,CAAC;IACxD,gBAAgB,IAAI,YAAY,EAAE,GAAG,SAAS,CAAC;IAC/C,aAAa,IAAI,SAAS,EAAE,GAAG,SAAS,CAAC;IACzC,aAAa,IAAI,SAAS,EAAE,GAAG,SAAS,CAAC;IACzC,iBAAiB,IAAI,MAAM,CAAC;IAC5B,UAAU,IAAI,eAAe,GAAG,SAAS,CAAC;IAG1C,uBAAuB,IAAI,OAAO,CAAC,kBAAkB,GAAG,SAAS,CAAC,CAAC;IACnE,eAAe,CAAC,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,cAAc,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,SAAS,EAAE,GAAG,SAAS,CAAC,CAAC;IACzI,eAAe,IAAI,OAAO,CAAC,SAAS,EAAE,GAAG,SAAS,CAAC,CAAC;IACpD,YAAY,IAAI,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC,CAAC;IAGrD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAGzB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/C,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5E,cAAc,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAC7E,YAAY,CAAC,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE;YAAE,SAAS,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;CACtH"}

package/dist/types/strategy.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=strategy.js.map

package/dist/types/strategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"strategy.js","sourceRoot":"","sources":["../../src/types/strategy.ts"],"names":[],"mappings":""}

package/dist/utils/logger/dsl.d.ts

@@ -0,0 +1,8 @@
+/**
+ * DSL logger instance. DSL code imports from here.
+ */
+import { type LogLevel } from "../logger.js";
+export type { LogLevel };
+export { setLogLevel } from "../logger.js";
+export declare const logger: import("../logger.js").Logger;
+//# sourceMappingURL=dsl.d.ts.map

package/dist/utils/logger/dsl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dsl.d.ts","sourceRoot":"","sources":["../../../src/utils/logger/dsl.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAgB,KAAK,QAAQ,EAAE,MAAM,cAAc,CAAC;AAE3D,YAAY,EAAE,QAAQ,EAAE,CAAC;AACzB,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C,eAAO,MAAM,MAAM,+BAAoC,CAAC"}

package/dist/utils/logger/dsl.js

@@ -0,0 +1,7 @@
+/**
+ * DSL logger instance. DSL code imports from here.
+ */
+import { createLogger } from "../logger.js";
+export { setLogLevel } from "../logger.js";
+export const logger = createLogger("[senpi-core][dsl]");
+//# sourceMappingURL=dsl.js.map

package/dist/utils/logger/dsl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dsl.js","sourceRoot":"","sources":["../../../src/utils/logger/dsl.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,YAAY,EAAiB,MAAM,cAAc,CAAC;AAG3D,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C,MAAM,CAAC,MAAM,MAAM,GAAG,YAAY,CAAC,mBAAmB,CAAC,CAAC"}

package/dist/utils/logger.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Shared structured logger factory. Components create a logger with a namespace.
+ */
+export type LogLevel = "debug" | "info" | "warn" | "error";
+export declare function setLogLevel(level: LogLevel): void;
+export interface Logger {
+    debug(message: string, meta?: unknown): void;
+    info(message: string, meta?: unknown): void;
+    warn(message: string, meta?: unknown): void;
+    error(message: string, meta?: unknown): void;
+}
+export declare function createLogger(namespace: string): Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/utils/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAW3D,wBAAgB,WAAW,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI,CAEjD;AAMD,MAAM,WAAW,MAAM;IACrB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC7C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC5C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC5C,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CAC9C;AAED,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAuCtD"}

package/dist/utils/logger.js

@@ -0,0 +1,65 @@
+/**
+ * Shared structured logger factory. Components create a logger with a namespace.
+ */
+const levelOrder = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+};
+let minLevel = "info";
+export function setLogLevel(level) {
+    minLevel = level;
+}
+function shouldLog(level) {
+    return levelOrder[level] >= levelOrder[minLevel];
+}
+export function createLogger(namespace) {
+    return {
+        debug(message, meta) {
+            if (!shouldLog("debug"))
+                return;
+            const prefix = `${namespace} [debug]`;
+            if (meta !== undefined) {
+                console.log(prefix, message, meta);
+            }
+            else {
+                console.log(prefix, message);
+            }
+        },
+        info(message, meta) {
+            if (!shouldLog("info"))
+                return;
+            const prefix = `${namespace} [info]`;
+            if (meta !== undefined) {
+                console.log(prefix, message, meta);
+            }
+            else {
+                console.log(prefix, message);
+            }
+        },
+        warn(message, meta) {
+            if (!shouldLog("warn"))
+                return;
+            const prefix = `${namespace} [warn]`;
+            if (meta !== undefined) {
+                console.warn(prefix, message, meta);
+            }
+            else {
+                console.warn(prefix, message);
+            }
+        },
+        error(message, meta) {
+            if (!shouldLog("error"))
+                return;
+            const prefix = `${namespace} [error]`;
+            if (meta !== undefined) {
+                console.error(prefix, message, meta);
+            }
+            else {
+                console.error(prefix, message);
+            }
+        },
+    };
+}
+//# sourceMappingURL=logger.js.map

package/dist/utils/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,MAAM,UAAU,GAA6B;IAC3C,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC;IACP,IAAI,EAAE,CAAC;IACP,KAAK,EAAE,CAAC;CACT,CAAC;AAEF,IAAI,QAAQ,GAAa,MAAM,CAAC;AAEhC,MAAM,UAAU,WAAW,CAAC,KAAe;IACzC,QAAQ,GAAG,KAAK,CAAC;AACnB,CAAC;AAED,SAAS,SAAS,CAAC,KAAe;IAChC,OAAO,UAAU,CAAC,KAAK,CAAC,IAAI,UAAU,CAAC,QAAQ,CAAC,CAAC;AACnD,CAAC;AASD,MAAM,UAAU,YAAY,CAAC,SAAiB;IAC5C,OAAO;QACL,KAAK,CAAC,OAAe,EAAE,IAAc;YACnC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;gBAAE,OAAO;YAChC,MAAM,MAAM,GAAG,GAAG,SAAS,UAAU,CAAC;YACtC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;gBACvB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;YACrC,CAAC;iBAAM,CAAC;gBACN,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;YAC/B,CAAC;QACH,CAAC;QACD,IAAI,CAAC,OAAe,EAAE,IAAc;YAClC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC;gBAAE,OAAO;YAC/B,MAAM,MAAM,GAAG,GAAG,SAAS,SAAS,CAAC;YACrC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;gBACvB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;YACrC,CAAC;iBAAM,CAAC;gBACN,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;YAC/B,CAAC;QACH,CAAC;QACD,IAAI,CAAC,OAAe,EAAE,IAAc;YAClC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC;gBAAE,OAAO;YAC/B,MAAM,MAAM,GAAG,GAAG,SAAS,SAAS,CAAC;YACrC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;gBACvB,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;YACtC,CAAC;iBAAM,CAAC;gBACN,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;YAChC,CAAC;QACH,CAAC;QACD,KAAK,CAAC,OAAe,EAAE,IAAc;YACnC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;gBAAE,OAAO;YAChC,MAAM,MAAM,GAAG,GAAG,SAAS,UAAU,CAAC;YACtC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;gBACvB,OAAO,CAAC,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;YACvC,CAAC;iBAAM,CAAC;gBACN,OAAO,CAAC,KAAK,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;YACjC,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/utils/response.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Shared response helpers: envelope unwrapping and type coercion.
+ * Used by senpi client, LLM decision, and scanner adapters.
+ */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/**
+ * Unwraps `{ success, data }` envelopes when present.
+ * When inner data is a record, preserves top-level success/error/message on it so callers do not lose them.
+ * Non-envelope payloads are returned unchanged.
+ */
+export declare function unwrapEnvelope<T>(input: unknown): T | unknown;
+export declare function asString(value: unknown): string | null;
+export declare function asNumber(value: unknown): number | null;
+//# sourceMappingURL=response.d.ts.map

package/dist/utils/response.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response.d.ts","sourceRoot":"","sources":["../../src/utils/response.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEzE;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,GAAG,CAAC,GAAG,OAAO,CAa7D;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAEtD;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAOtD"}

package/dist/utils/response.js

@@ -0,0 +1,44 @@
+/**
+ * Shared response helpers: envelope unwrapping and type coercion.
+ * Used by senpi client, LLM decision, and scanner adapters.
+ */
+export function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+/**
+ * Unwraps `{ success, data }` envelopes when present.
+ * When inner data is a record, preserves top-level success/error/message on it so callers do not lose them.
+ * Non-envelope payloads are returned unchanged.
+ */
+export function unwrapEnvelope(input) {
+    if (!isRecord(input))
+        return input;
+    const maybeEnvelope = input;
+    if (typeof maybeEnvelope.success !== "boolean" || !("data" in maybeEnvelope)) {
+        return input;
+    }
+    const inner = maybeEnvelope.data;
+    if (!isRecord(inner))
+        return inner;
+    const out = { ...inner };
+    if (typeof maybeEnvelope.error === "string" && !("error" in out))
+        out.error = maybeEnvelope.error;
+    if (typeof maybeEnvelope.message === "string" && !("message" in out))
+        out.message = maybeEnvelope.message;
+    if (!("success" in out))
+        out.success = maybeEnvelope.success;
+    return out;
+}
+export function asString(value) {
+    return typeof value === "string" ? value : null;
+}
+export function asNumber(value) {
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    if (typeof value === "string") {
+        const n = Number(value);
+        return Number.isFinite(n) ? n : null;
+    }
+    return null;
+}
+//# sourceMappingURL=response.js.map

package/dist/utils/response.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"response.js","sourceRoot":"","sources":["../../src/utils/response.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAC;AACrD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAI,KAAc;IAC9C,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACnC,MAAM,aAAa,GAAG,KAAgF,CAAC;IACvG,IAAI,OAAO,aAAa,CAAC,OAAO,KAAK,SAAS,IAAI,CAAC,CAAC,MAAM,IAAI,aAAa,CAAC,EAAE,CAAC;QAC7E,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,KAAK,GAAG,aAAa,CAAC,IAAI,CAAC;IACjC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,KAAU,CAAC;IACxC,MAAM,GAAG,GAAG,EAAE,GAAG,KAAK,EAA6B,CAAC;IACpD,IAAI,OAAO,aAAa,CAAC,KAAK,KAAK,QAAQ,IAAI,CAAC,CAAC,OAAO,IAAI,GAAG,CAAC;QAAE,GAAG,CAAC,KAAK,GAAG,aAAa,CAAC,KAAK,CAAC;IAClG,IAAI,OAAO,aAAa,CAAC,OAAO,KAAK,QAAQ,IAAI,CAAC,CAAC,SAAS,IAAI,GAAG,CAAC;QAAE,GAAG,CAAC,OAAO,GAAG,aAAa,CAAC,OAAO,CAAC;IAC1G,IAAI,CAAC,CAAC,SAAS,IAAI,GAAG,CAAC;QAAE,GAAG,CAAC,OAAO,GAAG,aAAa,CAAC,OAAO,CAAC;IAC7D,OAAO,GAAQ,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;AAClD,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACtE,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QACxB,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACvC,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export declare const VERSION = "1.0.0";
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,OAAO,UAAU,CAAC"}

package/dist/version.js

@@ -0,0 +1,2 @@
+export const VERSION = "1.0.0";
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC"}

package/examples/.env.example

@@ -0,0 +1,15 @@
+# Environment variables for @senpi/trading-runtime
+# Copy to .env and fill in values.
+
+# Required for live trading
+SENPI_API_KEY=
+
+# Wallet address used in strategy YAML templates (referenced as ${WALLET_ADDRESS})
+WALLET_ADDRESS=
+
+# Optional: directory for DSL position state files
+# Default: ~/.openclaw/senpi-state
+DSL_STATE_DIR=
+
+# MCP server URL — only change for non-prod testing
+# SENPI_MCP_URL=https://mcp.prod.senpi.ai/mcp

package/examples/README.md

@@ -0,0 +1,75 @@
+# Scanners Module Examples
+
+These examples are real clients of the standalone scanners module.
+
+If you are integrating the module as a consumer for the first time, start with `scanners-consumer-quickstart.mjs`.
+
+Each example imports from a built `dist/` entrypoint, so build first:
+
+```bash
+npm run build
+```
+
+Run examples:
+
+```bash
+node examples/scanners-single-strategy.mjs
+node examples/scanners-multi-strategy.mjs
+node examples/scanners-scheduled-events.mjs
+node examples/scanners-senpi-provider-client.mjs
+node examples/scanners-consumer-quickstart.mjs
+node examples/scanners-emerging-movers-v4.mjs
+
+# Requires env vars (see below)
+node examples/scanners-live-mcp.mjs
+```
+
+What each example demonstrates:
+
+1. `scanners-consumer-quickstart.mjs`
+- Smallest consumer-oriented setup
+- Which imports to use
+- Required `createScannerRuntimeModule(...)` options
+- Manual `runOnce(...)` flow and `querySignals(...)`
+
+2. `scanners-single-strategy.mjs`
+- One strategy with `prescreener`, `oi-tracker`, `momentum`, `emerging-movers`
+- Manual `runOnce` flow and signal query
+
+3. `scanners-multi-strategy.mjs`
+- Two strategies sharing scanner ids
+- Different scanner configs per strategy and isolated outputs
+
+4. `scanners-scheduled-events.mjs`
+- Interval-driven execution with `start()` / `stop()`
+- Pub/sub lifecycle events (`start`, `complete`, `skip`, `error`)
+
+5. `scanners-senpi-provider-client.mjs`
+- Uses `createSenpiScannerProviders(...)` with a **mock** `callTool` client
+- Demonstrates provider wiring for `prescreener`, `momentum`, and `emerging-movers`
+
+6. `scanners-emerging-movers-v4.mjs`
+- Showcases all five v4 signal types: FIRST_JUMP, CONTRIB_EXPLOSION, IMMEDIATE_MOVER, NEW_ENTRY_DEEP, DEEP_CLIMBER
+- Simulates a 50-token SM leaderboard evolving over 4 scans
+- Production-like v4 config with all detection thresholds
+- Prints signals with priority, reasons, factors, and summary breakdown
+
+7. `scanners-live-mcp.mjs`
+- Connects to the **real Senpi MCP server** using `@modelcontextprotocol/sdk`
+- Bridges `Client.callTool` → `SenpiToolClient` interface
+- Runs all four scanners against live market data and prints results
+- Requires env vars:
+  ```bash
+  export SENPI_API_KEY="your-api-key"
+  export SENPI_MCP_URL="https://mcp.prod.senpi.ai/mcp"
+  ```
+
+## Strategy YAML templates
+
+See [`strategies/`](./strategies/README.md) for production-ready YAML
+configs you can copy, fill in your wallet address, and load directly:
+
+```bash
+openclaw senpi trading-strategy create -p examples/strategies/wolf.yaml
+```
+

package/examples/scanners-consumer-quickstart.mjs

@@ -0,0 +1,134 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  createScannerRuntimeModule,
+  momentumScanner,
+  prescreenerScanner,
+} from "../dist/index.js";
+
+function createInstruments() {
+  return [
+    {
+      name: "BTC",
+      isDelisted: false,
+      maxLeverage: 10,
+      context: {
+        markPx: 105,
+        prevDayPx: 100,
+        midPx: 105,
+        dayNtlVlm: 80_000_000,
+        openInterest: 2_000_000_000,
+        funding: 0.001,
+      },
+    },
+    {
+      name: "ETH",
+      isDelisted: false,
+      maxLeverage: 8,
+      context: {
+        markPx: 101,
+        prevDayPx: 100,
+        midPx: 101,
+        dayNtlVlm: 40_000_000,
+        openInterest: 1_000_000_000,
+        funding: 0.001,
+      },
+    },
+  ];
+}
+
+function createCandles() {
+  return {
+    BTC: {
+      candles: {
+        "1h": [
+          { timestamp: 1, open: 100, high: 102, low: 99, close: 100, volume: 1000 },
+          { timestamp: 2, open: 100, high: 106, low: 100, close: 105, volume: 1400 },
+        ],
+      },
+    },
+    ETH: {
+      candles: {
+        "1h": [
+          { timestamp: 1, open: 100, high: 101, low: 99, close: 100, volume: 900 },
+          { timestamp: 2, open: 100, high: 101, low: 99, close: 100.2, volume: 920 },
+        ],
+      },
+    },
+  };
+}
+
+async function main() {
+  const stateDir = await mkdtemp(join(tmpdir(), "scanners-consumer-quickstart-"));
+
+  // Required pieces:
+  // - stateDir
+  // - at least one strategy
+  // - scanner factories
+  // - provider functions required by those scanners
+  const scannerModule = createScannerRuntimeModule({
+    stateDir,
+    strategies: [
+      {
+        id: "alpha",
+        name: "Alpha",
+        scannerOverrides: {
+          momentum: {
+            config: {
+              timeframe: "1h",
+              minMovePct: 1.5,
+              maxCandidates: 20,
+              minDayVolume: 1_000_000,
+              minSignalScore: 0.2,
+              requirePrescreened: true,
+            },
+          },
+        },
+      },
+    ],
+    scanners: [prescreenerScanner, momentumScanner],
+    providers: {
+      getInstruments: async () => createInstruments(),
+      getCandles: async () => createCandles(),
+    },
+  });
+
+  scannerModule.on("scanner:run:complete", (event) => {
+    console.log(
+      "complete:",
+      event.scannerId,
+      "status=",
+      event.result.status,
+      "signals=",
+      event.result.signals.length,
+    );
+  });
+
+  try {
+    // Manual operation
+    await scannerModule.runOnce("alpha", "prescreener");
+    await scannerModule.runOnce("alpha", "momentum");
+
+    const signals = await scannerModule.querySignals({
+      strategyId: "alpha",
+      scannerId: "momentum",
+      limit: 10,
+    });
+
+    console.log("persisted momentum signals =", signals.length);
+
+    // Scheduled operation is also available:
+    // await scannerModule.start();
+    // ...
+    // await scannerModule.stop();
+  } finally {
+    await scannerModule.stop();
+    await rm(stateDir, { recursive: true, force: true });
+  }
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});