@openfinclaw/fin-strategy-engine 0.0.1

package/src/builtin-strategies/rsi-mean-reversion.test.ts

@@ -0,0 +1,143 @@
+import { describe, expect, it } from "vitest";
+import type { OHLCV } from "../../../fin-shared-types/src/types.js";
+import { BacktestEngine } from "../backtest-engine.js";
+import { rsi } from "../indicators.js";
+import type { BacktestConfig } from "../types.js";
+import { createRsiMeanReversion } from "./rsi-mean-reversion.js";
+
+function makeBar(index: number, close: number): OHLCV {
+  return {
+    timestamp: 1000000 + index * 86400000,
+    open: close,
+    high: close * 1.01,
+    low: close * 0.99,
+    close,
+    volume: 1000,
+  };
+}
+
+describe("RSI Mean Reversion strategy", () => {
+  it("creates strategy with default parameters", () => {
+    const strategy = createRsiMeanReversion();
+    expect(strategy.id).toBe("rsi-mean-reversion");
+    expect(strategy.parameters.period).toBe(14);
+    expect(strategy.parameters.oversold).toBe(30);
+    expect(strategy.parameters.overbought).toBe(70);
+  });
+
+  it("creates strategy with custom parameters", () => {
+    const strategy = createRsiMeanReversion({
+      period: 7,
+      oversold: 25,
+      overbought: 75,
+      sizePct: 50,
+    });
+    expect(strategy.parameters.period).toBe(7);
+    expect(strategy.parameters.oversold).toBe(25);
+    expect(strategy.parameters.overbought).toBe(75);
+  });
+
+  it("buys on oversold RSI and sells on overbought RSI", async () => {
+    // Create price data that produces known RSI values:
+    // Start flat, then sharp drop (RSI < 30), then sharp rise (RSI > 70)
+    const prices: number[] = [];
+    // 20 bars flat at 100 (RSI neutral)
+    for (let i = 0; i < 20; i++) prices.push(100);
+    // 5 bars dropping sharply (RSI drops toward oversold)
+    prices.push(97, 93, 88, 82, 75);
+    // 10 bars rising sharply (RSI rises toward overbought)
+    prices.push(80, 88, 96, 105, 115, 125, 135, 145, 155, 165);
+
+    const data = prices.map((p, i) => makeBar(i, p));
+    const strategy = createRsiMeanReversion({
+      period: 14,
+      oversold: 30,
+      overbought: 70,
+      sizePct: 100,
+    });
+    const config: BacktestConfig = {
+      capital: 10000,
+      commissionRate: 0,
+      slippageBps: 0,
+      market: "crypto",
+    };
+
+    const engine = new BacktestEngine();
+    const result = await engine.run(strategy, data, config);
+
+    // Verify RSI actually crosses thresholds
+    const closes = data.map((d) => d.close);
+    const rsiValues = rsi(closes, 14);
+
+    // Find first oversold bar
+    let oversoldBar = -1;
+    for (let i = 0; i < rsiValues.length; i++) {
+      if (!Number.isNaN(rsiValues[i]!) && rsiValues[i]! < 30) {
+        oversoldBar = i;
+        break;
+      }
+    }
+
+    // Find first overbought bar after oversold
+    let overboughtBar = -1;
+    for (let i = oversoldBar + 1; i < rsiValues.length; i++) {
+      if (!Number.isNaN(rsiValues[i]!) && rsiValues[i]! > 70) {
+        overboughtBar = i;
+        break;
+      }
+    }
+
+    // RSI should have crossed both thresholds
+    expect(oversoldBar).toBeGreaterThan(-1);
+    expect(overboughtBar).toBeGreaterThan(oversoldBar);
+
+    // Strategy should have at least 1 trade
+    expect(result.totalTrades).toBeGreaterThanOrEqual(1);
+  });
+
+  it("returns no trades during warm-up period", async () => {
+    // Only 10 bars — not enough for RSI(14)
+    const data: OHLCV[] = [];
+    for (let i = 0; i < 10; i++) {
+      data.push(makeBar(i, 100 + i));
+    }
+
+    const strategy = createRsiMeanReversion({ period: 14 });
+    const config: BacktestConfig = {
+      capital: 10000,
+      commissionRate: 0,
+      slippageBps: 0,
+      market: "crypto",
+    };
+
+    const engine = new BacktestEngine();
+    const result = await engine.run(strategy, data, config);
+
+    expect(result.totalTrades).toBe(0);
+  });
+
+  it("does not double-buy when already in position", async () => {
+    // Multiple oversold readings — should only buy once
+    const prices: number[] = [];
+    for (let i = 0; i < 20; i++) prices.push(100);
+    // Keep dropping to stay oversold
+    for (let i = 0; i < 10; i++) prices.push(75 - i);
+
+    const data = prices.map((p, i) => makeBar(i, p));
+    const strategy = createRsiMeanReversion({ period: 14, oversold: 30 });
+    const config: BacktestConfig = {
+      capital: 10000,
+      commissionRate: 0,
+      slippageBps: 0,
+      market: "crypto",
+    };
+
+    const engine = new BacktestEngine();
+    const result = await engine.run(strategy, data, config);
+
+    // Should have at most 1 open position worth of trades
+    // (the auto-close at end counts as the exit)
+    const buySignals = result.trades.filter((t) => t.reason.includes("oversold"));
+    expect(buySignals.length).toBeLessThanOrEqual(1);
+  });
+});

package/src/builtin-strategies/rsi-mean-reversion.ts

@@ -0,0 +1,74 @@
+import type { OHLCV } from "../../../fin-shared-types/src/types.js";
+import type { Signal, StrategyContext, StrategyDefinition } from "../types.js";
+
+/**
+ * RSI Mean Reversion strategy.
+ * Buy when RSI drops below oversold threshold.
+ * Sell when RSI rises above overbought threshold.
+ */
+export function createRsiMeanReversion(params?: {
+  period?: number;
+  oversold?: number;
+  overbought?: number;
+  sizePct?: number;
+  symbol?: string;
+}): StrategyDefinition {
+  const period = params?.period ?? 14;
+  const oversold = params?.oversold ?? 30;
+  const overbought = params?.overbought ?? 70;
+  const sizePct = params?.sizePct ?? 100;
+  const symbol = params?.symbol ?? "BTC/USDT";
+
+  return {
+    id: "rsi-mean-reversion",
+    name: "RSI Mean Reversion",
+    version: "1.0.0",
+    markets: ["crypto", "equity"],
+    symbols: [symbol],
+    timeframes: ["1d"],
+    parameters: { period, oversold, overbought, sizePct },
+    parameterRanges: {
+      period: { min: 7, max: 28, step: 7 },
+      oversold: { min: 20, max: 40, step: 5 },
+      overbought: { min: 60, max: 80, step: 5 },
+      sizePct: { min: 10, max: 100, step: 10 },
+    },
+
+    async onBar(bar: OHLCV, ctx: StrategyContext): Promise<Signal | null> {
+      const rsiValues = ctx.indicators.rsi(period);
+      const len = rsiValues.length;
+      if (len < 1) return null;
+
+      const currentRsi = rsiValues[len - 1]!;
+      if (Number.isNaN(currentRsi)) return null;
+
+      const hasLong = ctx.portfolio.positions.some((p) => p.side === "long");
+
+      // RSI below oversold → buy
+      if (currentRsi < oversold && !hasLong) {
+        return {
+          action: "buy",
+          symbol,
+          sizePct,
+          orderType: "market",
+          reason: `RSI oversold: ${currentRsi.toFixed(1)} < ${oversold}`,
+          confidence: 0.6,
+        };
+      }
+
+      // RSI above overbought → sell
+      if (currentRsi > overbought && hasLong) {
+        return {
+          action: "sell",
+          symbol,
+          sizePct: 100,
+          orderType: "market",
+          reason: `RSI overbought: ${currentRsi.toFixed(1)} > ${overbought}`,
+          confidence: 0.6,
+        };
+      }
+
+      return null;
+    },
+  };
+}

package/src/builtin-strategies/sma-crossover.test.ts

@@ -0,0 +1,113 @@
+import { describe, expect, it } from "vitest";
+import type { OHLCV } from "../../../fin-shared-types/src/types.js";
+import { BacktestEngine } from "../backtest-engine.js";
+import { sma } from "../indicators.js";
+import type { BacktestConfig } from "../types.js";
+import { createSmaCrossover } from "./sma-crossover.js";
+
+function makeBar(index: number, close: number): OHLCV {
+  return {
+    timestamp: 1000000 + index * 86400000,
+    open: close,
+    high: close * 1.01,
+    low: close * 0.99,
+    close,
+    volume: 1000,
+  };
+}
+
+describe("SMA Crossover strategy", () => {
+  it("creates strategy with default parameters", () => {
+    const strategy = createSmaCrossover();
+    expect(strategy.id).toBe("sma-crossover");
+    expect(strategy.parameters.fastPeriod).toBe(10);
+    expect(strategy.parameters.slowPeriod).toBe(30);
+  });
+
+  it("creates strategy with custom parameters", () => {
+    const strategy = createSmaCrossover({ fastPeriod: 5, slowPeriod: 20, sizePct: 50 });
+    expect(strategy.parameters.fastPeriod).toBe(5);
+    expect(strategy.parameters.slowPeriod).toBe(20);
+    expect(strategy.parameters.sizePct).toBe(50);
+  });
+
+  it("buys on golden cross and sells on death cross", async () => {
+    // Design prices so that SMA(3) crosses above SMA(5) clearly.
+    // Then later SMA(3) crosses below SMA(5).
+    const prices = [
+      100,
+      100,
+      100,
+      100,
+      100, // bars 0-4: flat
+      102,
+      105,
+      110,
+      115,
+      120, // bars 5-9: rise (golden cross)
+      115,
+      108,
+      100,
+      95,
+      90, // bars 10-14: drop (death cross)
+    ];
+
+    const data = prices.map((p, i) => makeBar(i, p));
+    const strategy = createSmaCrossover({ fastPeriod: 3, slowPeriod: 5, sizePct: 100 });
+    const config: BacktestConfig = {
+      capital: 10000,
+      commissionRate: 0,
+      slippageBps: 0,
+      market: "crypto",
+    };
+
+    const engine = new BacktestEngine();
+    const result = await engine.run(strategy, data, config);
+
+    // Verify crossover happened by checking indicators
+    const closes = data.map((d) => d.close);
+    const fast = sma(closes, 3);
+    const slow = sma(closes, 5);
+
+    // Find golden cross
+    let goldenBar = -1;
+    for (let i = 1; i < closes.length; i++) {
+      if (
+        !Number.isNaN(fast[i]!) &&
+        !Number.isNaN(slow[i]!) &&
+        !Number.isNaN(fast[i - 1]!) &&
+        !Number.isNaN(slow[i - 1]!) &&
+        fast[i - 1]! <= slow[i - 1]! &&
+        fast[i]! > slow[i]!
+      ) {
+        goldenBar = i;
+        break;
+      }
+    }
+
+    expect(goldenBar).toBeGreaterThan(-1);
+    // Strategy should have at least 1 trade
+    expect(result.totalTrades).toBeGreaterThanOrEqual(1);
+    // Entry should be at the golden cross bar's close price
+    if (result.trades.length > 0) {
+      expect(result.trades[0]!.entryPrice).toBeCloseTo(closes[goldenBar]!, 0);
+    }
+  });
+
+  it("returns null during warm-up period", async () => {
+    // Only 3 bars — not enough for SMA(10)
+    const data = [makeBar(0, 100), makeBar(1, 101), makeBar(2, 102)];
+    const strategy = createSmaCrossover({ fastPeriod: 10, slowPeriod: 30 });
+    const config: BacktestConfig = {
+      capital: 10000,
+      commissionRate: 0,
+      slippageBps: 0,
+      market: "crypto",
+    };
+
+    const engine = new BacktestEngine();
+    const result = await engine.run(strategy, data, config);
+
+    expect(result.totalTrades).toBe(0);
+  });
+});

package/src/builtin-strategies/sma-crossover.ts

@@ -0,0 +1,85 @@
+import type { OHLCV } from "../../../fin-shared-types/src/types.js";
+import type { Signal, StrategyContext, StrategyDefinition } from "../types.js";
+
+/**
+ * SMA Crossover strategy.
+ * Buy when SMA(fast) crosses above SMA(slow).
+ * Sell when SMA(fast) crosses below SMA(slow).
+ */
+export function createSmaCrossover(params?: {
+  fastPeriod?: number;
+  slowPeriod?: number;
+  sizePct?: number;
+  symbol?: string;
+}): StrategyDefinition {
+  const fastPeriod = params?.fastPeriod ?? 10;
+  const slowPeriod = params?.slowPeriod ?? 30;
+  const sizePct = params?.sizePct ?? 100;
+  const symbol = params?.symbol ?? "BTC/USDT";
+
+  return {
+    id: "sma-crossover",
+    name: "SMA Crossover",
+    version: "1.0.0",
+    markets: ["crypto", "equity"],
+    symbols: [symbol],
+    timeframes: ["1d"],
+    parameters: { fastPeriod, slowPeriod, sizePct },
+    parameterRanges: {
+      fastPeriod: { min: 5, max: 50, step: 5 },
+      slowPeriod: { min: 20, max: 200, step: 10 },
+      sizePct: { min: 10, max: 100, step: 10 },
+    },
+
+    async onBar(_bar: OHLCV, ctx: StrategyContext): Promise<Signal | null> {
+      const fastSma = ctx.indicators.sma(fastPeriod);
+      const slowSma = ctx.indicators.sma(slowPeriod);
+
+      const len = fastSma.length;
+      if (len < 2) return null;
+
+      const currFast = fastSma[len - 1]!;
+      const currSlow = slowSma[len - 1]!;
+      const prevFast = fastSma[len - 2]!;
+      const prevSlow = slowSma[len - 2]!;
+
+      // Skip if any value is NaN (warm-up period)
+      if (
+        Number.isNaN(currFast) ||
+        Number.isNaN(currSlow) ||
+        Number.isNaN(prevFast) ||
+        Number.isNaN(prevSlow)
+      ) {
+        return null;
+      }
+
+      const hasLong = ctx.portfolio.positions.some((p) => p.side === "long");
+
+      // Golden cross: fast crosses above slow → buy
+      if (prevFast <= prevSlow && currFast > currSlow && !hasLong) {
+        return {
+          action: "buy",
+          symbol,
+          sizePct,
+          orderType: "market",
+          reason: `SMA golden cross: fast(${fastPeriod})=${currFast.toFixed(2)} > slow(${slowPeriod})=${currSlow.toFixed(2)}`,
+          confidence: 0.7,
+        };
+      }
+
+      // Death cross: fast crosses below slow → sell
+      if (prevFast >= prevSlow && currFast < currSlow && hasLong) {
+        return {
+          action: "sell",
+          symbol,
+          sizePct: 100,
+          orderType: "market",
+          reason: `SMA death cross: fast(${fastPeriod})=${currFast.toFixed(2)} < slow(${slowPeriod})=${currSlow.toFixed(2)}`,
+          confidence: 0.7,
+        };
+      }
+
+      return null;
+    },
+  };
+}

package/src/builtin-strategies/trend-following-momentum.test.ts

@@ -0,0 +1,228 @@
+import { describe, expect, it } from "vitest";
+import type { OHLCV } from "../../../fin-shared-types/src/types.js";
+import { BacktestEngine } from "../backtest-engine.js";
+import type { BacktestConfig } from "../types.js";
+import { createTrendFollowingMomentum } from "./trend-following-momentum.js";
+
+function makeBar(index: number, close: number, overrides?: Partial<OHLCV>): OHLCV {
+  return {
+    timestamp: 1000000 + index * 86400000,
+    open: close,
+    high: close * 1.01,
+    low: close * 0.99,
+    close,
+    volume: 1000,
+    ...overrides,
+  };
+}
+
+const config: BacktestConfig = {
+  capital: 10000,
+  commissionRate: 0,
+  slippageBps: 0,
+  market: "crypto",
+};
+
+describe("Trend-Following Momentum strategy", () => {
+  it("creates strategy with default parameters", () => {
+    const strategy = createTrendFollowingMomentum();
+    expect(strategy.id).toBe("trend-following-momentum");
+    expect(strategy.name).toBe("Trend-Following Momentum");
+    expect(strategy.parameters.fastEma).toBe(12);
+    expect(strategy.parameters.slowEma).toBe(26);
+    expect(strategy.parameters.macdFast).toBe(12);
+    expect(strategy.parameters.macdSlow).toBe(26);
+    expect(strategy.parameters.macdSignal).toBe(9);
+    expect(strategy.parameters.rsiPeriod).toBe(14);
+    expect(strategy.parameters.rsiOverbought).toBe(75);
+    expect(strategy.parameters.atrPeriod).toBe(14);
+    expect(strategy.parameters.atrStopMultiplier).toBe(2.0);
+    expect(strategy.parameters.atrProfitMultiplier).toBe(3.0);
+    expect(strategy.parameters.maxSizePct).toBe(80);
+
+    // Verify parameterRanges exist for all numeric params
+    expect(strategy.parameterRanges).toBeDefined();
+    expect(strategy.parameterRanges!.fastEma).toEqual({ min: 5, max: 50, step: 1 });
+    expect(strategy.parameterRanges!.slowEma).toEqual({ min: 10, max: 100, step: 2 });
+    expect(strategy.parameterRanges!.atrStopMultiplier).toEqual({ min: 1.0, max: 4.0, step: 0.5 });
+  });
+
+  it("creates strategy with custom parameters", () => {
+    const strategy = createTrendFollowingMomentum({
+      fastEma: 8,
+      slowEma: 21,
+      macdFast: 8,
+      macdSlow: 21,
+      macdSignal: 5,
+      rsiPeriod: 10,
+      rsiOverbought: 70,
+      atrPeriod: 10,
+      atrStopMultiplier: 1.5,
+      atrProfitMultiplier: 4.0,
+      maxSizePct: 60,
+      symbol: "ETH/USDT",
+    });
+    expect(strategy.parameters.fastEma).toBe(8);
+    expect(strategy.parameters.slowEma).toBe(21);
+    expect(strategy.parameters.macdFast).toBe(8);
+    expect(strategy.parameters.macdSlow).toBe(21);
+    expect(strategy.parameters.macdSignal).toBe(5);
+    expect(strategy.parameters.rsiPeriod).toBe(10);
+    expect(strategy.parameters.rsiOverbought).toBe(70);
+    expect(strategy.parameters.atrPeriod).toBe(10);
+    expect(strategy.parameters.atrStopMultiplier).toBe(1.5);
+    expect(strategy.parameters.atrProfitMultiplier).toBe(4.0);
+    expect(strategy.parameters.maxSizePct).toBe(60);
+    expect(strategy.symbols).toEqual(["ETH/USDT"]);
+  });
+
+  it("returns null during warm-up period", async () => {
+    // Only 5 bars — insufficient for EMA(26), MACD(12,26,9), RSI(14), ATR(14)
+    const data = [
+      makeBar(0, 100),
+      makeBar(1, 101),
+      makeBar(2, 102),
+      makeBar(3, 103),
+      makeBar(4, 104),
+    ];
+    const strategy = createTrendFollowingMomentum();
+
+    const engine = new BacktestEngine();
+    const result = await engine.run(strategy, data, config);
+
+    expect(result.totalTrades).toBe(0);
+  });
+
+  it("generates buy signal on EMA golden cross with MACD confirmation", async () => {
+    // Use small indicator periods to trigger signals with fewer bars.
+    // Phase 1: gentle decline (brings RSI low, fast EMA below slow EMA)
+    // Phase 2: choppy base (RSI normalizes near 50)
+    // Phase 3: gentle rise (triggers golden cross while RSI is still moderate)
+    const prices: number[] = [];
+    // Phase 1: decline from 120 to 106 over 15 bars
+    for (let i = 0; i < 15; i++) prices.push(120 - i);
+    // Phase 2: choppy base around 105
+    prices.push(105, 104, 106, 103, 105, 104, 106, 104, 105, 104);
+    // Phase 3: gentle rise
+    for (let i = 1; i <= 15; i++) prices.push(104 + i * 0.8);
+
+    const data = prices.map((p, i) => makeBar(i, p));
+    const strategy = createTrendFollowingMomentum({
+      fastEma: 3,
+      slowEma: 5,
+      macdFast: 3,
+      macdSlow: 5,
+      macdSignal: 2,
+      rsiPeriod: 3,
+      atrPeriod: 3,
+    });
+
+    const engine = new BacktestEngine();
+    const result = await engine.run(strategy, data, config);
+
+    // The decline→chop→rise pattern should trigger at least one buy entry
+    expect(result.totalTrades).toBeGreaterThanOrEqual(1);
+  });
+
+  it("does not buy when already holding long position", async () => {
+    // Create prices that produce two potential golden cross signals
+    // but the second should be ignored because we're already long
+    const prices: number[] = [];
+    // Flat baseline
+    for (let i = 0; i < 15; i++) prices.push(100);
+    // First rise → golden cross + buy
+    for (let i = 1; i <= 10; i++) prices.push(100 + i * 3);
+    // Small dip (not enough for death cross or MACD negative with small periods)
+    for (let i = 0; i < 3; i++) prices.push(128);
+    // Second rise → would be another buy if not already long
+    for (let i = 1; i <= 10; i++) prices.push(128 + i * 3);
+
+    const data = prices.map((p, i) => makeBar(i, p));
+    const strategy = createTrendFollowingMomentum({
+      fastEma: 3,
+      slowEma: 5,
+      macdFast: 3,
+      macdSlow: 5,
+      macdSignal: 2,
+      rsiPeriod: 3,
+      atrPeriod: 3,
+      rsiOverbought: 90, // High threshold so RSI doesn't block
+    });
+
+    const engine = new BacktestEngine();
+    const result = await engine.run(strategy, data, config);
+
+    // Count buy entries — there should be at most a few (not double entries)
+    const buyEntries = result.trades.filter((t) => t.reason.includes("Trend-following buy"));
+    // If multiple trades exist, each buy must follow a sell (no double buys)
+    for (let i = 1; i < buyEntries.length; i++) {
+      expect(buyEntries[i]!.entryTime).toBeGreaterThan(buyEntries[i - 1]!.exitTime);
+    }
+  });
+
+  it("sets dynamic stopLoss and takeProfit on buy signals", async () => {
+    // Same decline→chop→rise data that triggers a buy
+    const prices: number[] = [];
+    for (let i = 0; i < 15; i++) prices.push(120 - i);
+    prices.push(105, 104, 106, 103, 105, 104, 106, 104, 105, 104);
+    for (let i = 1; i <= 15; i++) prices.push(104 + i * 0.8);
+
+    const data = prices.map((p, i) => makeBar(i, p));
+    const strategy = createTrendFollowingMomentum({
+      fastEma: 3,
+      slowEma: 5,
+      macdFast: 3,
+      macdSlow: 5,
+      macdSignal: 2,
+      rsiPeriod: 3,
+      atrPeriod: 3,
+      atrStopMultiplier: 2.0,
+      atrProfitMultiplier: 3.0,
+    });
+
+    // Run onBar manually to capture the signal with stopLoss/takeProfit
+    // (BacktestEngine doesn't store these on TradeRecord)
+    const memory = new Map<string, unknown>();
+    let buySignal: { stopLoss?: number; takeProfit?: number; confidence: number } | null = null;
+
+    for (let i = 0; i < data.length; i++) {
+      const bar = data[i]!;
+      const history = data.slice(0, i + 1);
+      const closes = history.map((b) => b.close);
+      const highs = history.map((b) => b.high);
+      const lows = history.map((b) => b.low);
+
+      // Import indicators inline for manual context building
+      const { ema, rsi, macd, atr } = await import("../indicators.js");
+
+      const ctx = {
+        portfolio: { equity: 10000, cash: 10000, positions: [] as { side: string }[] },
+        history,
+        indicators: {
+          sma: () => [],
+          ema: (period: number) => ema(closes, period),
+          rsi: (period: number) => rsi(closes, period),
+          macd: (fast?: number, slow?: number, signal?: number) => macd(closes, fast, slow, signal),
+          bollingerBands: () => ({ upper: [], middle: [], lower: [] }),
+          atr: (period?: number) => atr(highs, lows, closes, period),
+        },
+        regime: "sideways" as const,
+        memory,
+        log: () => {},
+      };
+
+      const signal = await strategy.onBar(bar, ctx);
+      if (signal && signal.action === "buy") {
+        buySignal = signal;
+        break;
+      }
+    }
+
+    expect(buySignal).not.toBeNull();
+    expect(buySignal!.stopLoss).toBeDefined();
+    expect(buySignal!.takeProfit).toBeDefined();
+    expect(buySignal!.stopLoss!).toBeLessThan(buySignal!.takeProfit!);
+    expect(buySignal!.confidence).toBeGreaterThanOrEqual(0.3);
+    expect(buySignal!.confidence).toBeLessThanOrEqual(0.95);
+  });
+});