@openfinclaw/fin-strategy-engine 0.0.1

package/src/builtin-strategies/multi-timeframe-confluence.test.ts

@@ -0,0 +1,287 @@
+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 { createMultiTimeframeConfluence } from "./multi-timeframe-confluence.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("Multi-Timeframe Confluence strategy", () => {
+  it("creates strategy with default parameters", () => {
+    const strategy = createMultiTimeframeConfluence();
+    expect(strategy.id).toBe("multi-timeframe-confluence");
+    expect(strategy.name).toBe("Multi-Timeframe Confluence");
+    expect(strategy.parameters.longSma).toBe(200);
+    expect(strategy.parameters.mediumEma).toBe(50);
+    expect(strategy.parameters.shortEma).toBe(20);
+    expect(strategy.parameters.rsiPeriod).toBe(7);
+    expect(strategy.parameters.rsiOversold).toBe(35);
+    expect(strategy.parameters.rsiOverbought).toBe(65);
+    expect(strategy.parameters.bbPeriod).toBe(10);
+    expect(strategy.parameters.bbStdDev).toBe(2.0);
+    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(70);
+    expect(strategy.parameters.minConfluenceScore).toBe(3);
+
+    expect(strategy.parameterRanges).toBeDefined();
+    expect(strategy.parameterRanges!.longSma).toEqual({ min: 50, max: 300, step: 50 });
+    expect(strategy.parameterRanges!.minConfluenceScore).toEqual({ min: 2, max: 5, step: 1 });
+  });
+
+  it("creates strategy with custom parameters", () => {
+    const strategy = createMultiTimeframeConfluence({
+      longSma: 100,
+      mediumEma: 30,
+      shortEma: 10,
+      rsiPeriod: 5,
+      rsiOversold: 30,
+      rsiOverbought: 70,
+      bbPeriod: 15,
+      bbStdDev: 1.5,
+      atrPeriod: 10,
+      atrStopMultiplier: 1.5,
+      atrProfitMultiplier: 4.0,
+      maxSizePct: 50,
+      minConfluenceScore: 2,
+      symbol: "ETH/USDT",
+    });
+    expect(strategy.parameters.longSma).toBe(100);
+    expect(strategy.parameters.mediumEma).toBe(30);
+    expect(strategy.parameters.shortEma).toBe(10);
+    expect(strategy.parameters.rsiPeriod).toBe(5);
+    expect(strategy.parameters.rsiOversold).toBe(30);
+    expect(strategy.parameters.rsiOverbought).toBe(70);
+    expect(strategy.parameters.bbPeriod).toBe(15);
+    expect(strategy.parameters.bbStdDev).toBe(1.5);
+    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(50);
+    expect(strategy.parameters.minConfluenceScore).toBe(2);
+    expect(strategy.symbols).toEqual(["ETH/USDT"]);
+  });
+
+  it("returns null during warm-up period", async () => {
+    // Use small params: longSma:10 needs index >= 9 for valid SMA
+    // Give only 5 bars — not enough for SMA(10)
+    const data = [
+      makeBar(0, 100),
+      makeBar(1, 101),
+      makeBar(2, 102),
+      makeBar(3, 103),
+      makeBar(4, 104),
+    ];
+    const strategy = createMultiTimeframeConfluence({
+      longSma: 10,
+      mediumEma: 5,
+      shortEma: 3,
+      rsiPeriod: 3,
+      bbPeriod: 3,
+      bbStdDev: 2,
+      atrPeriod: 3,
+      minConfluenceScore: 3,
+    });
+
+    const engine = new BacktestEngine();
+    const result = await engine.run(strategy, data, config);
+
+    expect(result.totalTrades).toBe(0);
+  });
+
+  it("generates buy on confluence of long-term uptrend and short-term pullback", async () => {
+    // Test the onBar logic directly with a mock IndicatorLib to verify
+    // the confluence scoring and buy conditions work correctly.
+    const strategy = createMultiTimeframeConfluence({
+      longSma: 10,
+      mediumEma: 5,
+      shortEma: 3,
+      rsiPeriod: 3,
+      rsiOversold: 35,
+      rsiOverbought: 65,
+      bbPeriod: 3,
+      bbStdDev: 2,
+      atrPeriod: 3,
+      minConfluenceScore: 3,
+    });
+
+    const bar = makeBar(20, 105);
+    // Mock indicators that satisfy all confluence conditions:
+    // smaRising: currSma(100) > prevSma(99) AND close(105) > currSma(100) → 1
+    // structure: close(105) > ema50(103) AND ema50(103) > sma(100) → 1
+    // emaStack: ema20(104) > ema50(103) → 1
+    // longScore = 3
+    // rsiPullback: RSI(30) < 35 → 1
+    // shortScore = 1
+    // totalScore = 4 >= 3, RSI turning up: 30 > 25
+    const mockIndicators = {
+      sma: () => Array(20).fill(NaN).concat([99, 100]),
+      ema: (period: number) => {
+        if (period === 5) return Array(20).fill(NaN).concat([102, 103]);
+        return Array(20).fill(NaN).concat([103, 104]); // shortEma
+      },
+      rsi: () => Array(20).fill(NaN).concat([25, 30]),
+      bollingerBands: () => ({
+        upper: Array(21).fill(NaN).concat([110]),
+        middle: Array(21).fill(NaN).concat([105]),
+        lower: Array(21).fill(NaN).concat([100]),
+      }),
+      atr: () => Array(20).fill(NaN).concat([1, 2]),
+      macd: () => ({ macd: [], signal: [], histogram: [] }),
+    };
+
+    const memory = new Map<string, unknown>();
+    const ctx = {
+      portfolio: {
+        equity: 10000,
+        cash: 10000,
+        positions: [] as {
+          side: "long";
+          symbol: string;
+          quantity: number;
+          entryPrice: number;
+          currentPrice: number;
+          unrealizedPnl: number;
+        }[],
+      },
+      history: Array(22).fill(bar),
+      indicators: mockIndicators,
+      regime: "sideways" as const,
+      memory,
+      log: () => {},
+    };
+
+    const signal = await strategy.onBar(bar, ctx);
+    expect(signal).not.toBeNull();
+    expect(signal!.action).toBe("buy");
+    expect(signal!.confidence).toBeGreaterThanOrEqual(0.3);
+    expect(signal!.stopLoss).toBeDefined();
+    expect(signal!.takeProfit).toBeDefined();
+    expect(memory.get("entryConfluence")).toBe(4);
+    expect(memory.get("partialExitDone")).toBe(false);
+  });
+
+  it("does not buy when long-term trend is down", async () => {
+    const strategy = createMultiTimeframeConfluence({
+      longSma: 10,
+      mediumEma: 5,
+      shortEma: 3,
+      rsiPeriod: 3,
+      rsiOversold: 35,
+      rsiOverbought: 65,
+      bbPeriod: 3,
+      bbStdDev: 2,
+      atrPeriod: 3,
+      minConfluenceScore: 3,
+    });
+
+    const prices: number[] = [];
+
+    // 15 bars declining from 120 to ~80 (SMA10 falling, price below SMA)
+    for (let i = 0; i < 15; i++) prices.push(120 - i * 2.67);
+
+    // Brief dip and partial recovery — RSI may go oversold, but longScore < 2
+    // because SMA is falling and price is below SMA
+    prices.push(78, 76, 75, 74, 73);
+    for (let i = 0; i < 5; i++) prices.push(75 + i * 0.5);
+
+    const data = prices.map((p, i) => makeBar(i, p));
+    const engine = new BacktestEngine();
+    const result = await engine.run(strategy, data, config);
+
+    // No buy should occur: downtrend means longScore < 2
+    expect(result.totalTrades).toBe(0);
+  });
+
+  it("executes partial exit on RSI overbought reversal", async () => {
+    // Test partial exit logic with mock IndicatorLib.
+    // Simulate: holding a position, RSI > overbought (65) and declining.
+    const strategy = createMultiTimeframeConfluence({
+      longSma: 10,
+      mediumEma: 5,
+      shortEma: 3,
+      rsiPeriod: 3,
+      rsiOversold: 35,
+      rsiOverbought: 65,
+      bbPeriod: 3,
+      bbStdDev: 2,
+      atrPeriod: 3,
+      atrStopMultiplier: 2.0,
+      atrProfitMultiplier: 3.0,
+      minConfluenceScore: 3,
+    });
+
+    const bar = makeBar(25, 150);
+
+    // Set up memory as if we entered earlier (partialExitDone = false)
+    const memory = new Map<string, unknown>();
+    memory.set("highestClose", 155);
+    memory.set("partialExitDone", false);
+    memory.set("entryConfluence", 4);
+
+    // Mock indicators: RSI overbought (70) and declining (prevRsi=75)
+    // Price still above SMA (no breakdown), no EMA collapse, no trailing stop
+    const mockIndicators = {
+      sma: () => Array(25).fill(NaN).concat([140, 141]),
+      ema: (period: number) => {
+        if (period === 5) return Array(25).fill(NaN).concat([146, 148]);
+        return Array(25).fill(NaN).concat([148, 149]); // shortEma
+      },
+      rsi: () => Array(25).fill(NaN).concat([75, 70]), // overbought and declining
+      bollingerBands: () => ({
+        upper: Array(26).fill(NaN).concat([160]),
+        middle: Array(26).fill(NaN).concat([145]),
+        lower: Array(26).fill(NaN).concat([130]),
+      }),
+      atr: () => Array(25).fill(NaN).concat([3, 3]),
+      macd: () => ({ macd: [], signal: [], histogram: [] }),
+    };
+
+    const ctx = {
+      portfolio: {
+        equity: 10000,
+        cash: 5000,
+        positions: [
+          {
+            side: "long" as const,
+            symbol: "BTC/USDT",
+            quantity: 1,
+            entryPrice: 105,
+            currentPrice: 150,
+            unrealizedPnl: 45,
+          },
+        ],
+      },
+      history: Array(27).fill(bar),
+      indicators: mockIndicators,
+      regime: "sideways" as const,
+      memory,
+      log: () => {},
+    };
+
+    const signal = await strategy.onBar(bar, ctx);
+    expect(signal).not.toBeNull();
+    expect(signal!.action).toBe("sell");
+    expect(signal!.sizePct).toBe(50);
+    expect(signal!.reason).toBe("Partial exit: RSI overbought reversal");
+    expect(memory.get("partialExitDone")).toBe(true);
+  });
+});

package/src/builtin-strategies/multi-timeframe-confluence.ts

@@ -0,0 +1,253 @@
+import type { OHLCV } from "../../../fin-shared-types/src/types.js";
+import type { Signal, StrategyContext, StrategyDefinition } from "../types.js";
+
+/**
+ * Multi-Timeframe Confluence composite strategy.
+ *
+ * Combines long-term trend alignment (SMA200, EMA50/20 structure) with
+ * short-term pullback signals (RSI oversold, Bollinger Band lower touch)
+ * to enter high-probability long positions during confirmed uptrends.
+ *
+ * Buy when: long-term uptrend confirmed (score >= 2) + short-term pullback
+ * detected (score >= 1) + RSI turning up + total confluence >= minConfluenceScore.
+ *
+ * Sell when: SMA200 breakdown, EMA structure collapse, or ATR trailing stop hit.
+ * Partial exit when RSI overbought + turning down (first occurrence only).
+ */
+export function createMultiTimeframeConfluence(params?: {
+  longSma?: number;
+  mediumEma?: number;
+  shortEma?: number;
+  rsiPeriod?: number;
+  rsiOversold?: number;
+  rsiOverbought?: number;
+  bbPeriod?: number;
+  bbStdDev?: number;
+  atrPeriod?: number;
+  atrStopMultiplier?: number;
+  atrProfitMultiplier?: number;
+  maxSizePct?: number;
+  minConfluenceScore?: number;
+  symbol?: string;
+}): StrategyDefinition {
+  const longSma = params?.longSma ?? 200;
+  const mediumEma = params?.mediumEma ?? 50;
+  const shortEma = params?.shortEma ?? 20;
+  const rsiPeriod = params?.rsiPeriod ?? 7;
+  const rsiOversold = params?.rsiOversold ?? 35;
+  const rsiOverbought = params?.rsiOverbought ?? 65;
+  const bbPeriod = params?.bbPeriod ?? 10;
+  const bbStdDev = params?.bbStdDev ?? 2.0;
+  const atrPeriod = params?.atrPeriod ?? 14;
+  const atrStopMultiplier = params?.atrStopMultiplier ?? 2.0;
+  const atrProfitMultiplier = params?.atrProfitMultiplier ?? 3.0;
+  const maxSizePct = params?.maxSizePct ?? 70;
+  const minConfluenceScore = params?.minConfluenceScore ?? 3;
+  const symbol = params?.symbol ?? "BTC/USDT";
+
+  return {
+    id: "multi-timeframe-confluence",
+    name: "Multi-Timeframe Confluence",
+    version: "1.0.0",
+    markets: ["crypto", "equity"],
+    symbols: [symbol],
+    timeframes: ["1d"],
+    parameters: {
+      longSma,
+      mediumEma,
+      shortEma,
+      rsiPeriod,
+      rsiOversold,
+      rsiOverbought,
+      bbPeriod,
+      bbStdDev,
+      atrPeriod,
+      atrStopMultiplier,
+      atrProfitMultiplier,
+      maxSizePct,
+      minConfluenceScore,
+    },
+    parameterRanges: {
+      longSma: { min: 50, max: 300, step: 50 },
+      mediumEma: { min: 20, max: 100, step: 10 },
+      shortEma: { min: 5, max: 50, step: 5 },
+      rsiPeriod: { min: 3, max: 21, step: 2 },
+      rsiOversold: { min: 20, max: 45, step: 5 },
+      rsiOverbought: { min: 55, max: 80, step: 5 },
+      bbPeriod: { min: 5, max: 30, step: 5 },
+      bbStdDev: { min: 1.0, max: 3.0, step: 0.5 },
+      atrPeriod: { min: 7, max: 28, step: 7 },
+      atrStopMultiplier: { min: 1.0, max: 4.0, step: 0.5 },
+      atrProfitMultiplier: { min: 1.5, max: 6.0, step: 0.5 },
+      maxSizePct: { min: 20, max: 100, step: 10 },
+      minConfluenceScore: { min: 2, max: 5, step: 1 },
+    },
+
+    async onBar(bar: OHLCV, ctx: StrategyContext): Promise<Signal | null> {
+      // Compute all indicators
+      const smaArr = ctx.indicators.sma(longSma);
+      const medEmaArr = ctx.indicators.ema(mediumEma);
+      const shortEmaArr = ctx.indicators.ema(shortEma);
+      const rsiArr = ctx.indicators.rsi(rsiPeriod);
+      const bb = ctx.indicators.bollingerBands(bbPeriod, bbStdDev);
+      const atrArr = ctx.indicators.atr(atrPeriod);
+
+      const len = smaArr.length;
+      if (len < 2) return null;
+
+      const currSma = smaArr[len - 1]!;
+      const prevSma = smaArr[len - 2]!;
+      const currEma50 = medEmaArr[len - 1]!;
+      const currEma20 = shortEmaArr[len - 1]!;
+      const currRsi = rsiArr[len - 1]!;
+      const prevRsi = rsiArr[len - 2]!;
+      const currBBLower = bb.lower[len - 1]!;
+      const currAtr = atrArr[len - 1]!;
+
+      // NaN guard: need at least longSma bars for SMA warmup
+      if (
+        Number.isNaN(currSma) ||
+        Number.isNaN(prevSma) ||
+        Number.isNaN(currEma50) ||
+        Number.isNaN(currEma20) ||
+        Number.isNaN(currRsi) ||
+        Number.isNaN(prevRsi) ||
+        Number.isNaN(currBBLower) ||
+        Number.isNaN(currAtr)
+      ) {
+        return null;
+      }
+
+      // Regime filter: skip during crisis
+      if (ctx.regime === "crisis") return null;
+
+      const hasLong = ctx.portfolio.positions.some((p) => p.side === "long");
+
+      // --- SELL / PARTIAL EXIT conditions (check first when holding) ---
+      if (hasLong) {
+        // Update highest close for trailing stop
+        const storedHighest = (ctx.memory.get("highestClose") as number) ?? bar.close;
+        const highestClose = Math.max(storedHighest, bar.close);
+        ctx.memory.set("highestClose", highestClose);
+
+        // Partial exit: RSI overbought reversal (one-time)
+        const partialExitDone = ctx.memory.get("partialExitDone") as boolean | undefined;
+        if (!partialExitDone && currRsi > rsiOverbought && currRsi < prevRsi) {
+          ctx.memory.set("partialExitDone", true);
+          return {
+            action: "sell",
+            symbol,
+            sizePct: 50,
+            orderType: "market",
+            reason: "Partial exit: RSI overbought reversal",
+            confidence: 0.7,
+          };
+        }
+
+        // SMA200 breakdown: price fell below long-term trend
+        if (bar.close < currSma) {
+          ctx.memory.delete("longConfluence");
+          ctx.memory.delete("shortConfluence");
+          ctx.memory.delete("entryConfluence");
+          ctx.memory.delete("highestClose");
+          ctx.memory.delete("partialExitDone");
+          return {
+            action: "sell",
+            symbol,
+            sizePct: 100,
+            orderType: "market",
+            reason: `SMA breakdown: close=${bar.close.toFixed(2)} < SMA(${longSma})=${currSma.toFixed(2)}`,
+            confidence: 0.8,
+          };
+        }
+
+        // EMA structure collapse: full bearish alignment
+        if (currEma20 < currEma50 && currEma50 < currSma) {
+          ctx.memory.delete("longConfluence");
+          ctx.memory.delete("shortConfluence");
+          ctx.memory.delete("entryConfluence");
+          ctx.memory.delete("highestClose");
+          ctx.memory.delete("partialExitDone");
+          return {
+            action: "sell",
+            symbol,
+            sizePct: 100,
+            orderType: "market",
+            reason: `EMA structure collapse: EMA(${shortEma})=${currEma20.toFixed(2)} < EMA(${mediumEma})=${currEma50.toFixed(2)} < SMA(${longSma})=${currSma.toFixed(2)}`,
+            confidence: 0.85,
+          };
+        }
+
+        // Trailing stop: price dropped more than atrStopMultiplier * ATR from highest
+        if (bar.close < highestClose - atrStopMultiplier * currAtr) {
+          ctx.memory.delete("longConfluence");
+          ctx.memory.delete("shortConfluence");
+          ctx.memory.delete("entryConfluence");
+          ctx.memory.delete("highestClose");
+          ctx.memory.delete("partialExitDone");
+          return {
+            action: "sell",
+            symbol,
+            sizePct: 100,
+            orderType: "market",
+            reason: `Trailing stop: close=${bar.close.toFixed(2)} < highest=${highestClose.toFixed(2)} - ${atrStopMultiplier}*ATR=${currAtr.toFixed(2)}`,
+            confidence: 0.75,
+          };
+        }
+      }
+
+      // --- BUY conditions ---
+      if (!hasLong) {
+        // Long-term confluence scoring (3 items, each 0 or 1)
+        const smaRising = currSma > prevSma && bar.close > currSma ? 1 : 0;
+        const structure = bar.close > currEma50 && currEma50 > currSma ? 1 : 0;
+        const emaStack = currEma20 > currEma50 ? 1 : 0;
+        const longScore = smaRising + structure + emaStack;
+
+        // Short-term pullback scoring (2 items)
+        const rsiPullback = currRsi < rsiOversold ? 1 : 0;
+        const bbTouch = bar.close <= currBBLower ? 1 : 0;
+        const shortScore = rsiPullback + bbTouch;
+
+        const totalScore = longScore + shortScore;
+
+        // All conditions must be met
+        const longTrendStrong = longScore >= 2;
+        const pullbackHappening = shortScore >= 1;
+        const rsiTurningUp = currRsi > prevRsi;
+        const confluenceMet = totalScore >= minConfluenceScore;
+
+        if (longTrendStrong && pullbackHappening && rsiTurningUp && confluenceMet) {
+          // Confidence = 0.3 + 0.12 * totalScore, clamped [0.3, 0.95]
+          const confidence = Math.max(0.3, Math.min(0.95, 0.3 + 0.12 * totalScore));
+
+          const stopLoss = bar.close - atrStopMultiplier * currAtr;
+          const takeProfit = bar.close + atrProfitMultiplier * currAtr;
+
+          // Store state in memory
+          ctx.memory.set("longConfluence", longScore);
+          ctx.memory.set("shortConfluence", shortScore);
+          ctx.memory.set("entryConfluence", totalScore);
+          ctx.memory.set("highestClose", bar.close);
+          ctx.memory.set("partialExitDone", false);
+
+          // Dynamic position sizing
+          const sizePct = Math.min(maxSizePct, Math.max(20, confidence * 90));
+
+          return {
+            action: "buy",
+            symbol,
+            sizePct,
+            orderType: "market",
+            reason: `Confluence buy: longScore=${longScore} shortScore=${shortScore} total=${totalScore} RSI=${currRsi.toFixed(1)}`,
+            confidence,
+            stopLoss,
+            takeProfit,
+          };
+        }
+      }
+
+      return null;
+    },
+  };
+}