@openfinclaw/fin-strategy-engine 0.0.1

package/src/builtin-strategies/custom-rule-engine.ts

@@ -0,0 +1,274 @@
+/**
+ * Declarative rule engine for custom trading strategies.
+ * Parses simple expressions (AND, OR, <, >, <=, >=, ==) and generates
+ * a StrategyDefinition with an onBar function.
+ *
+ * Supported indicators: rsi, sma, ema, macd.histogram, bb.upper, bb.lower, atr
+ * Supported price fields: close, open, high, low, volume
+ * Supports user-defined parameter references.
+ */
+
+import type { OHLCV } from "../../../fin-shared-types/src/types.js";
+import type { StrategyDefinition, StrategyContext, Signal } from "../types.js";
+
+type Operator = "<" | ">" | "<=" | ">=" | "==";
+type LogicalOp = "AND" | "OR";
+
+interface Comparison {
+  left: string;
+  op: Operator;
+  right: string;
+}
+
+interface RuleNode {
+  type: "comparison" | "logical";
+  comparison?: Comparison;
+  logicalOp?: LogicalOp;
+  children?: RuleNode[];
+}
+
+const OPERATORS: Operator[] = ["<=", ">=", "==", "<", ">"];
+
+function tokenize(expr: string): string[] {
+  // Normalize whitespace and split while preserving operators
+  const normalized = expr
+    .replace(/\bAND\b/gi, " AND ")
+    .replace(/\bOR\b/gi, " OR ")
+    .replace(/<=/g, " <= ")
+    .replace(/>=/g, " >= ")
+    .replace(/==/g, " == ")
+    .replace(/(?<!=)(?<!<)(?<!>)<(?!=)/g, " < ")
+    .replace(/(?<!=)(?<!<)(?<!>)>(?!=)/g, " > ");
+
+  return normalized.split(/\s+/).filter((t) => t.length > 0);
+}
+
+function parseRule(expr: string): RuleNode {
+  const tokens = tokenize(expr);
+  if (tokens.length === 0) {
+    throw new Error("Empty rule expression");
+  }
+
+  // Split by OR first (lower precedence), then AND
+  const orParts = splitByLogical(tokens, "OR");
+  if (orParts.length > 1) {
+    return {
+      type: "logical",
+      logicalOp: "OR",
+      children: orParts.map((part) => parseRule(part.join(" "))),
+    };
+  }
+
+  const andParts = splitByLogical(tokens, "AND");
+  if (andParts.length > 1) {
+    return {
+      type: "logical",
+      logicalOp: "AND",
+      children: andParts.map((part) => parseRule(part.join(" "))),
+    };
+  }
+
+  // Single comparison: left op right
+  if (tokens.length < 3) {
+    throw new Error(`Invalid comparison: "${tokens.join(" ")}". Expected: <left> <op> <right>`);
+  }
+
+  const op = tokens.find((t) => OPERATORS.includes(t as Operator)) as Operator | undefined;
+  if (!op) {
+    throw new Error(`No operator found in: "${tokens.join(" ")}". Use <, >, <=, >=, or ==`);
+  }
+
+  const opIdx = tokens.indexOf(op);
+  const left = tokens.slice(0, opIdx).join(".");
+  const right = tokens.slice(opIdx + 1).join(".");
+
+  return { type: "comparison", comparison: { left, op, right } };
+}
+
+function splitByLogical(tokens: string[], keyword: string): string[][] {
+  const parts: string[][] = [];
+  let current: string[] = [];
+  for (const t of tokens) {
+    if (t.toUpperCase() === keyword) {
+      if (current.length > 0) parts.push(current);
+      current = [];
+    } else {
+      current.push(t);
+    }
+  }
+  if (current.length > 0) parts.push(current);
+  return parts;
+}
+
+function resolveValue(
+  name: string,
+  bar: OHLCV,
+  ctx: StrategyContext,
+  params: Record<string, number>,
+): number {
+  // Try as a number literal first
+  const num = Number(name);
+  if (!Number.isNaN(num)) return num;
+
+  // Price fields
+  switch (name) {
+    case "close":
+      return bar.close;
+    case "open":
+      return bar.open;
+    case "high":
+      return bar.high;
+    case "low":
+      return bar.low;
+    case "volume":
+      return bar.volume;
+  }
+
+  // User parameters
+  if (name in params) return params[name]!;
+
+  // Indicators (take latest value)
+  const latest = (arr: number[]) => (arr.length > 0 ? arr[arr.length - 1]! : 0);
+
+  if (name === "rsi") return latest(ctx.indicators.rsi(params.rsiPeriod ?? 14));
+  if (name === "sma") return latest(ctx.indicators.sma(params.smaPeriod ?? 20));
+  if (name === "ema") return latest(ctx.indicators.ema(params.emaPeriod ?? 20));
+  if (name === "atr") return latest(ctx.indicators.atr(params.atrPeriod ?? 14));
+
+  // MACD sub-fields
+  if (name === "macd.histogram" || name === "macd.hist") {
+    const m = ctx.indicators.macd(
+      params.macdFast ?? 12,
+      params.macdSlow ?? 26,
+      params.macdSignal ?? 9,
+    );
+    return latest(m.histogram);
+  }
+  if (name === "macd.signal") {
+    const m = ctx.indicators.macd(
+      params.macdFast ?? 12,
+      params.macdSlow ?? 26,
+      params.macdSignal ?? 9,
+    );
+    return latest(m.signal);
+  }
+  if (name === "macd.macd" || name === "macd.line") {
+    const m = ctx.indicators.macd(
+      params.macdFast ?? 12,
+      params.macdSlow ?? 26,
+      params.macdSignal ?? 9,
+    );
+    return latest(m.macd);
+  }
+
+  // Bollinger Bands
+  if (name === "bb.upper") {
+    const bb = ctx.indicators.bollingerBands(params.bbPeriod ?? 20, params.bbStdDev ?? 2);
+    return latest(bb.upper);
+  }
+  if (name === "bb.lower") {
+    const bb = ctx.indicators.bollingerBands(params.bbPeriod ?? 20, params.bbStdDev ?? 2);
+    return latest(bb.lower);
+  }
+  if (name === "bb.middle") {
+    const bb = ctx.indicators.bollingerBands(params.bbPeriod ?? 20, params.bbStdDev ?? 2);
+    return latest(bb.middle);
+  }
+
+  throw new Error(`Unknown variable: "${name}"`);
+}
+
+function evaluateNode(
+  node: RuleNode,
+  bar: OHLCV,
+  ctx: StrategyContext,
+  params: Record<string, number>,
+): boolean {
+  if (node.type === "comparison" && node.comparison) {
+    const left = resolveValue(node.comparison.left, bar, ctx, params);
+    const right = resolveValue(node.comparison.right, bar, ctx, params);
+
+    switch (node.comparison.op) {
+      case "<":
+        return left < right;
+      case ">":
+        return left > right;
+      case "<=":
+        return left <= right;
+      case ">=":
+        return left >= right;
+      case "==":
+        return Math.abs(left - right) < 1e-10;
+    }
+  }
+
+  if (node.type === "logical" && node.children) {
+    if (node.logicalOp === "AND") {
+      return node.children.every((c) => evaluateNode(c, bar, ctx, params));
+    }
+    if (node.logicalOp === "OR") {
+      return node.children.some((c) => evaluateNode(c, bar, ctx, params));
+    }
+  }
+
+  return false;
+}
+
+export interface CustomRules {
+  buy: string;
+  sell: string;
+}
+
+export function buildCustomStrategy(
+  name: string,
+  rules: CustomRules,
+  params: Record<string, number>,
+  symbols?: string[],
+  timeframes?: string[],
+): StrategyDefinition {
+  // Parse rules upfront to catch errors early
+  const buyRule = parseRule(rules.buy);
+  const sellRule = parseRule(rules.sell);
+
+  return {
+    id: `custom-${Date.now()}`,
+    name,
+    version: "1.0.0",
+    markets: ["crypto"],
+    symbols: symbols ?? ["BTC/USDT"],
+    timeframes: timeframes ?? ["1d"],
+    parameters: { ...params },
+    async onBar(bar: OHLCV, ctx: StrategyContext): Promise<Signal | null> {
+      const hasPosition = ctx.portfolio.positions.some(
+        (p) => p.symbol === (symbols?.[0] ?? "BTC/USDT"),
+      );
+
+      if (!hasPosition && evaluateNode(buyRule, bar, ctx, params)) {
+        return {
+          action: "buy",
+          symbol: symbols?.[0] ?? "BTC/USDT",
+          sizePct: 10,
+          orderType: "market",
+          reason: `Custom rule: ${rules.buy}`,
+          confidence: 0.7,
+        };
+      }
+
+      if (hasPosition && evaluateNode(sellRule, bar, ctx, params)) {
+        return {
+          action: "sell",
+          symbol: symbols?.[0] ?? "BTC/USDT",
+          sizePct: 100,
+          orderType: "market",
+          reason: `Custom rule: ${rules.sell}`,
+          confidence: 0.7,
+        };
+      }
+
+      return null;
+    },
+  };
+}
+
+// Re-export for testing
+export { parseRule, evaluateNode, resolveValue };

package/src/builtin-strategies/macd-divergence.test.ts

@@ -0,0 +1,122 @@
+import { describe, expect, it } from "vitest";
+import type { OHLCV } from "../../../fin-shared-types/src/types.js";
+import { BacktestEngine } from "../backtest-engine.js";
+import { macd } from "../indicators.js";
+import type { BacktestConfig } from "../types.js";
+import { createMacdDivergence } from "./macd-divergence.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("MACD Divergence strategy", () => {
+  it("creates strategy with default parameters", () => {
+    const strategy = createMacdDivergence();
+    expect(strategy.id).toBe("macd-divergence");
+    expect(strategy.parameters.fastPeriod).toBe(12);
+    expect(strategy.parameters.slowPeriod).toBe(26);
+    expect(strategy.parameters.signalPeriod).toBe(9);
+    expect(strategy.parameters.sizePct).toBe(100);
+  });
+
+  it("creates strategy with custom parameters", () => {
+    const strategy = createMacdDivergence({
+      fastPeriod: 8,
+      slowPeriod: 21,
+      signalPeriod: 5,
+      sizePct: 50,
+    });
+    expect(strategy.parameters.fastPeriod).toBe(8);
+    expect(strategy.parameters.slowPeriod).toBe(21);
+    expect(strategy.parameters.signalPeriod).toBe(5);
+    expect(strategy.parameters.sizePct).toBe(50);
+  });
+
+  it("buys on bullish histogram cross and sells on bearish cross", async () => {
+    // Need: uptrend (positive histogram) → decline (negative) → recovery (positive) → decline (negative)
+    // Non-linear moves so MACD actually reacts (linear = flat MACD)
+    const prices: number[] = [];
+    // Phase 1: accelerating rise → positive histogram
+    for (let i = 0; i < 25; i++) prices.push(100 + i * i * 0.2);
+    // Phase 2: sharp decline → histogram crosses to negative
+    for (let i = 0; i < 15; i++) prices.push(prices[prices.length - 1] - 8 - i * 0.5);
+    // Phase 3: sharp recovery → histogram crosses back to positive
+    for (let i = 0; i < 15; i++) prices.push(prices[prices.length - 1] + 10 + i * 0.5);
+    // Phase 4: decline again → histogram crosses back to negative
+    for (let i = 0; i < 10; i++) prices.push(prices[prices.length - 1] - 10);
+
+    const data = prices.map((p, i) => makeBar(i, p));
+    const strategy = createMacdDivergence({
+      fastPeriod: 8,
+      slowPeriod: 17,
+      signalPeriod: 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 histogram actually crosses zero in both directions
+    const closes = data.map((d) => d.close);
+    const { histogram } = macd(closes, 8, 17, 5);
+
+    let bullishCross = false;
+    let bearishCross = false;
+    for (let i = 1; i < histogram.length; i++) {
+      if (
+        !Number.isNaN(histogram[i]) &&
+        !Number.isNaN(histogram[i - 1]) &&
+        histogram[i - 1] < 0 &&
+        histogram[i] >= 0
+      ) {
+        bullishCross = true;
+      }
+      if (
+        !Number.isNaN(histogram[i]) &&
+        !Number.isNaN(histogram[i - 1]) &&
+        histogram[i - 1] >= 0 &&
+        histogram[i] < 0
+      ) {
+        bearishCross = true;
+      }
+    }
+
+    expect(bullishCross).toBe(true);
+    expect(bearishCross).toBe(true);
+    expect(result.totalTrades).toBeGreaterThanOrEqual(1);
+  });
+
+  it("returns no trades during warm-up period", async () => {
+    // Only 20 bars — not enough for MACD(12,26,9)
+    const data: OHLCV[] = [];
+    for (let i = 0; i < 20; i++) {
+      data.push(makeBar(i, 100 + i));
+    }
+
+    const strategy = createMacdDivergence({ fastPeriod: 12, slowPeriod: 26, signalPeriod: 9 });
+    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/macd-divergence.ts

@@ -0,0 +1,77 @@
+import type { OHLCV } from "../../../fin-shared-types/src/types.js";
+import type { Signal, StrategyContext, StrategyDefinition } from "../types.js";
+
+/**
+ * MACD Divergence strategy.
+ * Buy when MACD histogram crosses from negative to positive.
+ * Sell when MACD histogram crosses from positive to negative.
+ */
+export function createMacdDivergence(params?: {
+  fastPeriod?: number;
+  slowPeriod?: number;
+  signalPeriod?: number;
+  sizePct?: number;
+  symbol?: string;
+}): StrategyDefinition {
+  const fastPeriod = params?.fastPeriod ?? 12;
+  const slowPeriod = params?.slowPeriod ?? 26;
+  const signalPeriod = params?.signalPeriod ?? 9;
+  const sizePct = params?.sizePct ?? 100;
+  const symbol = params?.symbol ?? "BTC/USDT";
+
+  return {
+    id: "macd-divergence",
+    name: "MACD Divergence",
+    version: "1.0.0",
+    markets: ["crypto", "equity"],
+    symbols: [symbol],
+    timeframes: ["1d"],
+    parameters: { fastPeriod, slowPeriod, signalPeriod, sizePct },
+    parameterRanges: {
+      fastPeriod: { min: 8, max: 20, step: 2 },
+      slowPeriod: { min: 20, max: 40, step: 2 },
+      signalPeriod: { min: 5, max: 15, step: 2 },
+      sizePct: { min: 10, max: 100, step: 10 },
+    },
+
+    async onBar(_bar: OHLCV, ctx: StrategyContext): Promise<Signal | null> {
+      const { histogram } = ctx.indicators.macd(fastPeriod, slowPeriod, signalPeriod);
+
+      const len = histogram.length;
+      if (len < 2) return null;
+
+      const curr = histogram[len - 1]!;
+      const prev = histogram[len - 2]!;
+
+      if (Number.isNaN(curr) || Number.isNaN(prev)) return null;
+
+      const hasLong = ctx.portfolio.positions.some((p) => p.side === "long");
+
+      // Histogram crosses from negative to positive → bullish, buy
+      if (prev < 0 && curr >= 0 && !hasLong) {
+        return {
+          action: "buy",
+          symbol,
+          sizePct,
+          orderType: "market",
+          reason: `MACD bullish cross: histogram ${prev.toFixed(4)} → ${curr.toFixed(4)}`,
+          confidence: 0.6,
+        };
+      }
+
+      // Histogram crosses from positive to negative → bearish, sell
+      if (prev >= 0 && curr < 0 && hasLong) {
+        return {
+          action: "sell",
+          symbol,
+          sizePct: 100,
+          orderType: "market",
+          reason: `MACD bearish cross: histogram ${prev.toFixed(4)} → ${curr.toFixed(4)}`,
+          confidence: 0.6,
+        };
+      }
+
+      return null;
+    },
+  };
+}