perp-cli 0.6.3 → 0.7.1

package/README.md

@@ -48,7 +48,7 @@ Same EVM key works for both Hyperliquid and Lighter.
 | `account` | Balance, positions, orders, margin |
 | `trade` | Market/limit/stop orders, close, scale, split execution |
 | `arb` | Funding rate arb — scan, exec, close, monitor (perp-perp & spot-perp) |
-| `bot` | TWAP, grid, DCA, trailing-stop bots |
+| `bot` | 19 strategies, APEX orchestrator, REFLECT analytics, presets |
 | `funds` | Deposit, withdraw, transfer, CCTP bridge |
 | `bridge` | Cross-chain USDC bridge (deBridge DLN) |
 | `risk` | Risk limits, liquidation distance, guardrails |
@@ -121,7 +121,12 @@ perp --json funds info                               # all routes & limits
 perp --json risk limits --max-leverage 5
 perp --json risk liquidation-distance
 
-# Bots
+# Bots (19 strategies)
+perp bot list-strategies                             # list all available strategies
+perp bot run <strategy> [symbol]                     # run any strategy
+perp bot apex [symbol]                               # APEX autonomous orchestrator
+perp bot reflect                                     # trading performance analysis
+perp bot preset-list                                 # list strategy presets
 perp --json bot twap <SYM> buy <SIZE> 30m
 perp --json bot grid <SYM> --range 5 --grids 10 --size 100
 

package/dist/api/public/hyperliquid.d.ts

@@ -1,4 +1,4 @@
-export interface HyperliquidAsset {
+interface HyperliquidAsset {
     symbol: string;
     funding: number;
     markPx: number;
@@ -9,10 +9,10 @@ export declare function parseHyperliquidMetaRaw(raw: unknown): {
     rates: Map<string, number>;
     prices: Map<string, number>;
 };
-export declare function fetchHyperliquidAllMids(): Promise<Record<string, string>>;
 export declare function fetchHyperliquidAllMidsRaw(): Promise<unknown>;
 export declare function pingHyperliquid(): Promise<{
     ok: boolean;
     latencyMs: number;
     status: number;
 }>;
+export {};

package/dist/api/public/hyperliquid.js

@@ -52,16 +52,6 @@ export function parseHyperliquidMetaRaw(raw) {
     });
     return { rates, prices };
 }
-export function fetchHyperliquidAllMids() {
-    return withCache("pub:hl:allMids", TTL_MARKET, async () => {
-        try {
-            return await hlPost("allMids");
-        }
-        catch {
-            return {};
-        }
-    });
-}
 export function fetchHyperliquidAllMidsRaw() {
     return withCache("pub:hl:allMids:raw", TTL_MARKET, () => hlPost("allMids").catch(() => null));
 }

package/dist/api/public/lighter.d.ts

@@ -1,4 +1,4 @@
-export interface LighterMarketDetail {
+interface LighterMarketDetail {
     marketId: number;
     symbol: string;
     lastTradePrice: number;
@@ -22,3 +22,4 @@ export declare function pingLighter(): Promise<{
     latencyMs: number;
     status: number;
 }>;
+export {};

package/dist/api/public/pacifica.d.ts

@@ -1,4 +1,4 @@
-export interface PacificaAsset {
+interface PacificaAsset {
     symbol: string;
     funding: number;
     mark: number;
@@ -15,3 +15,4 @@ export declare function pingPacifica(): Promise<{
     latencyMs: number;
     status: number;
 }>;
+export {};

package/dist/arb/index.d.ts

@@ -1,4 +1,7 @@
-export * from "./sizing.js";
-export * from "./utils.js";
-export * from "./state.js";
-export * from "./history-stats.js";
+export { computeMatchedSize, computeSpotPerpMatchedSize, reconcileArbFills } from "./sizing.js";
+export { SETTLEMENT_SCHEDULES, getLastSettlement, getMinutesSinceSettlement, aggressiveSettleBoost, estimateFundingUntilSettlement, computeBasisRisk, formatNotifyMessage, sendNotification, notifyIfEnabled, } from "./utils.js";
+export type { SettleStrategy, BasisRisk, ArbNotifyEvent } from "./utils.js";
+export { setStateFilePath, resetStateFilePath, loadArbState, saveArbState, addPosition, removePosition, updatePosition, getPositions, createInitialState, } from "./state.js";
+export type { ArbPositionState, ArbDaemonState } from "./state.js";
+export { computeEnhancedStats } from "./history-stats.js";
+export type { ArbTradeForStats, ExchangePairPerf, TimeOfDayPerf, EnhancedHistoryStats } from "./history-stats.js";

package/dist/arb/index.js

@@ -1,4 +1,5 @@
-export * from "./sizing.js";
-export * from "./utils.js";
-export * from "./state.js";
-export * from "./history-stats.js";
+// arb/ barrel — public API
+export { computeMatchedSize, computeSpotPerpMatchedSize, reconcileArbFills } from "./sizing.js";
+export { SETTLEMENT_SCHEDULES, getLastSettlement, getMinutesSinceSettlement, aggressiveSettleBoost, estimateFundingUntilSettlement, computeBasisRisk, formatNotifyMessage, sendNotification, notifyIfEnabled, } from "./utils.js";
+export { setStateFilePath, resetStateFilePath, loadArbState, saveArbState, addPosition, removePosition, updatePosition, getPositions, createInitialState, } from "./state.js";
+export { computeEnhancedStats } from "./history-stats.js";

package/dist/arb/sizing.d.ts

@@ -1,4 +1,4 @@
-import type { ExchangeAdapter } from "../exchanges/interface.js";
+import type { ExchangeAdapter } from "../exchanges/index.js";
 /**
  * Calculate the exact same size for both legs of an arb position,
  * respecting both exchanges' minimum order and size precision constraints.

package/dist/arb/state.d.ts

@@ -45,7 +45,7 @@ export declare function loadArbState(): ArbDaemonState | null;
  * If crash occurs mid-write, .tmp is partial but main file is intact.
  */
 export declare function saveArbState(state: ArbDaemonState): void;
-/** Add a position to the persisted state. */
+/** Add a position to the persisted state. Auto-initializes state if missing. */
 export declare function addPosition(pos: ArbPositionState): void;
 /** Remove a position by symbol from the persisted state. */
 export declare function removePosition(symbol: string): void;

package/dist/arb/state.js

@@ -62,11 +62,12 @@ export function saveArbState(state) {
     writeFileSync(tmpPath, json, { mode: 0o600 });
     renameSync(tmpPath, stateFilePath);
 }
-/** Add a position to the persisted state. */
+/** Add a position to the persisted state. Auto-initializes state if missing. */
 export function addPosition(pos) {
-    const state = loadArbState();
+    let state = loadArbState();
     if (!state) {
-        throw new Error("No daemon state found. Initialize state before adding positions.");
+        // State was lost — create minimal valid state to avoid losing position tracking
+        state = createInitialState({ minSpread: 0, closeSpread: 0, size: 0, holdDays: 0, bridgeCost: 0, maxPositions: 10, settleStrategy: "off" });
     }
     // Avoid duplicates by symbol
     state.positions = state.positions.filter(p => p.symbol !== pos.symbol);

package/dist/arb/utils.d.ts

@@ -1,7 +1,6 @@
 /**
  * Arb utilities: settlement timing strategy, basis risk monitoring, and webhook notifications.
  */
-import type { ExchangeAdapter } from "../exchanges/interface.js";
 /** Settlement schedules per exchange (UTC hours when settlement occurs) */
 export declare const SETTLEMENT_SCHEDULES: Record<string, number[]>;
 export type SettleStrategy = "block" | "aggressive" | "off";
@@ -47,15 +46,6 @@ export interface BasisRisk {
     divergencePct: number;
     warning: boolean;
 }
-/**
- * Check basis risk (mark price divergence) for open arb positions.
- * Fetches current mark prices from each exchange and computes divergence.
- */
-export declare function checkBasisRisk(positions: Array<{
-    symbol: string;
-    longExchange: string;
-    shortExchange: string;
-}>, adapters: Map<string, ExchangeAdapter>, maxDivergencePct?: number): Promise<BasisRisk[]>;
 /**
  * Compute basis risk from pre-fetched prices (no async, for use in tests and monitor).
  */

package/dist/arb/utils.js

@@ -89,48 +89,6 @@ export function estimateFundingUntilSettlement(hlHourlyRate, pacHourlyRate, posi
     const netFunding = hlCumulative - pacPayment;
     return { hlCumulative, pacPayment, netFunding };
 }
-/**
- * Check basis risk (mark price divergence) for open arb positions.
- * Fetches current mark prices from each exchange and computes divergence.
- */
-export async function checkBasisRisk(positions, adapters, maxDivergencePct = 3) {
-    const results = [];
-    for (const pos of positions) {
-        const longAdapter = adapters.get(pos.longExchange);
-        const shortAdapter = adapters.get(pos.shortExchange);
-        if (!longAdapter || !shortAdapter)
-            continue;
-        try {
-            const [longMarkets, shortMarkets] = await Promise.all([
-                longAdapter.getMarkets(),
-                shortAdapter.getMarkets(),
-            ]);
-            const longMarket = longMarkets.find(m => m.symbol.replace("-PERP", "").toUpperCase() === pos.symbol.toUpperCase());
-            const shortMarket = shortMarkets.find(m => m.symbol.replace("-PERP", "").toUpperCase() === pos.symbol.toUpperCase());
-            if (!longMarket || !shortMarket)
-                continue;
-            const longPrice = Number(longMarket.markPrice);
-            const shortPrice = Number(shortMarket.markPrice);
-            if (longPrice <= 0 || shortPrice <= 0)
-                continue;
-            const avgPrice = (longPrice + shortPrice) / 2;
-            const divergencePct = Math.abs(longPrice - shortPrice) / avgPrice * 100;
-            results.push({
-                symbol: pos.symbol,
-                longExchange: pos.longExchange,
-                shortExchange: pos.shortExchange,
-                longMarkPrice: longPrice,
-                shortMarkPrice: shortPrice,
-                divergencePct,
-                warning: divergencePct >= maxDivergencePct,
-            });
-        }
-        catch {
-            // Skip positions where we can't fetch prices
-        }
-    }
-    return results;
-}
 /**
  * Compute basis risk from pre-fetched prices (no async, for use in tests and monitor).
  */

package/dist/bot/apex/guard.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Guard: 2-phase trailing stop with profit-locking tiers.
+ * Phase 1: wide retrace tolerance while position builds.
+ * Phase 2: tiered profit floors (e.g., at 3% ROE lock 1%, at 6% lock 3%, etc.)
+ */
+export interface GuardConfig {
+    /** Max retrace from entry allowed in Phase 1 (percentage, e.g., 2 = 2%) */
+    phase1MaxRetrace: number;
+    /** ROE threshold to transition from Phase 1 to Phase 2 (percentage) */
+    phase2Trigger: number;
+    /** Profit-locking tiers: [roeTrigger, floorRoe] pairs sorted ascending */
+    profitTiers: [number, number][];
+    /** Hard stop loss from entry (percentage, e.g., 5 = -5%) */
+    hardStop: number;
+}
+export interface GuardState {
+    phase: 1 | 2;
+    peakRoe: number;
+    currentFloor: number;
+}
+export declare const GUARD_PRESETS: Record<string, GuardConfig>;
+export declare function createGuardState(): GuardState;
+export declare function evaluateGuard(roe: number, state: GuardState, config: GuardConfig): {
+    action: "hold" | "close";
+    newState: GuardState;
+};

package/dist/bot/apex/guard.js

@@ -0,0 +1,86 @@
+/**
+ * Guard: 2-phase trailing stop with profit-locking tiers.
+ * Phase 1: wide retrace tolerance while position builds.
+ * Phase 2: tiered profit floors (e.g., at 3% ROE lock 1%, at 6% lock 3%, etc.)
+ */
+export const GUARD_PRESETS = {
+    conservative: {
+        phase1MaxRetrace: 1.5,
+        phase2Trigger: 1.5,
+        profitTiers: [[1.5, 0.5], [3, 1.5], [5, 3], [8, 5], [12, 8]],
+        hardStop: 3,
+    },
+    moderate: {
+        phase1MaxRetrace: 2.5,
+        phase2Trigger: 2,
+        profitTiers: [[2, 0.5], [3, 1], [5, 2.5], [8, 5], [12, 8], [20, 15]],
+        hardStop: 5,
+    },
+    aggressive: {
+        phase1MaxRetrace: 4,
+        phase2Trigger: 3,
+        profitTiers: [[3, 1], [6, 3], [10, 6], [15, 10], [25, 18]],
+        hardStop: 8,
+    },
+};
+export function createGuardState() {
+    return { phase: 1, peakRoe: 0, currentFloor: 0 };
+}
+export function evaluateGuard(roe, state, config) {
+    // Update peak ROE
+    const peakRoe = Math.max(state.peakRoe, roe);
+    // Hard stop: always active
+    if (roe <= -config.hardStop) {
+        return {
+            action: "close",
+            newState: { ...state, peakRoe },
+        };
+    }
+    // ── Phase 1: wide retrace tolerance ──
+    if (state.phase === 1) {
+        // Check if we should transition to Phase 2
+        if (roe >= config.phase2Trigger) {
+            // Transition to Phase 2 — find the current floor
+            let floor = 0;
+            for (const [trigger, lockFloor] of config.profitTiers) {
+                if (roe >= trigger)
+                    floor = lockFloor;
+            }
+            return {
+                action: "hold",
+                newState: { phase: 2, peakRoe, currentFloor: floor },
+            };
+        }
+        // Phase 1: allow retrace up to phase1MaxRetrace from peak
+        const retrace = peakRoe - roe;
+        if (retrace > config.phase1MaxRetrace) {
+            return {
+                action: "close",
+                newState: { ...state, peakRoe },
+            };
+        }
+        return {
+            action: "hold",
+            newState: { phase: 1, peakRoe, currentFloor: 0 },
+        };
+    }
+    // ── Phase 2: tiered profit floors ──
+    // Update floor based on current ROE
+    let floor = state.currentFloor;
+    for (const [trigger, lockFloor] of config.profitTiers) {
+        if (roe >= trigger && lockFloor > floor) {
+            floor = lockFloor;
+        }
+    }
+    // Check if ROE dropped below current floor
+    if (roe < floor) {
+        return {
+            action: "close",
+            newState: { phase: 2, peakRoe, currentFloor: floor },
+        };
+    }
+    return {
+        action: "hold",
+        newState: { phase: 2, peakRoe, currentFloor: floor },
+    };
+}

package/dist/bot/apex/index.d.ts

@@ -0,0 +1,6 @@
+export { scoreOpportunity } from "./radar.js";
+export type { RadarScore } from "./radar.js";
+export { detectPulse, tierRank } from "./pulse.js";
+export type { PulseTier, PulseSignal } from "./pulse.js";
+export { evaluateGuard, createGuardState, GUARD_PRESETS } from "./guard.js";
+export type { GuardConfig, GuardState } from "./guard.js";

package/dist/bot/apex/index.js

@@ -0,0 +1,4 @@
+// apex/ barrel -- Radar + Pulse + Guard
+export { scoreOpportunity } from "./radar.js";
+export { detectPulse, tierRank } from "./pulse.js";
+export { evaluateGuard, createGuardState, GUARD_PRESETS } from "./guard.js";

package/dist/bot/apex/pulse.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Pulse: 5-tier signal taxonomy for momentum detection.
+ * FIRST_JUMP (100): first sector mover, OI + volume breakout
+ * CONTRIB_EXPLOSION (95): OI +15% AND volume 5x simultaneously
+ * IMMEDIATE_MOVER (80): OI +15% OR volume 5x
+ * NEW_ENTRY_DEEP (65): OI growth 8%+ with low volume (smart money)
+ * DEEP_CLIMBER (55): sustained OI climb 5%+ per window over 3+ scans
+ */
+import type { EnrichedSnapshot } from "../strategy-types.js";
+export type PulseTier = "FIRST_JUMP" | "CONTRIB_EXPLOSION" | "IMMEDIATE_MOVER" | "NEW_ENTRY_DEEP" | "DEEP_CLIMBER" | "NONE";
+export interface PulseSignal {
+    symbol: string;
+    tier: PulseTier;
+    confidence: number;
+    oiChange: number;
+    volumeRatio: number;
+}
+export declare function tierRank(tier: PulseTier): number;
+export declare function detectPulse(current: EnrichedSnapshot, history: Map<string, {
+    oi: number;
+    volume: number;
+}[]>): PulseSignal;

package/dist/bot/apex/pulse.js

@@ -0,0 +1,107 @@
+/**
+ * Pulse: 5-tier signal taxonomy for momentum detection.
+ * FIRST_JUMP (100): first sector mover, OI + volume breakout
+ * CONTRIB_EXPLOSION (95): OI +15% AND volume 5x simultaneously
+ * IMMEDIATE_MOVER (80): OI +15% OR volume 5x
+ * NEW_ENTRY_DEEP (65): OI growth 8%+ with low volume (smart money)
+ * DEEP_CLIMBER (55): sustained OI climb 5%+ per window over 3+ scans
+ */
+/** Tier ordering for comparison */
+const TIER_RANK = {
+    FIRST_JUMP: 100,
+    CONTRIB_EXPLOSION: 95,
+    IMMEDIATE_MOVER: 80,
+    NEW_ENTRY_DEEP: 65,
+    DEEP_CLIMBER: 55,
+    NONE: 0,
+};
+export function tierRank(tier) {
+    return TIER_RANK[tier];
+}
+export function detectPulse(current, history) {
+    const symbol = "unknown"; // caller sets the actual symbol
+    const currentOi = parseFloat(current.openInterest);
+    const currentVolume = current.volume24h;
+    const past = history.get(symbol) ?? [];
+    if (past.length === 0) {
+        return { symbol, tier: "NONE", confidence: 0, oiChange: 0, volumeRatio: 0 };
+    }
+    // Compare against the most recent historical entry
+    const prev = past[past.length - 1];
+    const oiChange = prev.oi > 0 ? (currentOi - prev.oi) / prev.oi : 0;
+    const volumeRatio = prev.volume > 0 ? currentVolume / prev.volume : 0;
+    // Thresholds
+    const oiBreakout = oiChange >= 0.15; // +15%
+    const volumeBreakout = volumeRatio >= 5; // 5x volume
+    const oiDeep = oiChange >= 0.08; // +8% OI
+    const lowVolume = volumeRatio < 1.5; // below 1.5x → quiet accumulation
+    // ── Tier detection (highest priority first) ──
+    // FIRST_JUMP: OI + volume breakout when no other symbol in sector moved
+    // Simplified: both OI and volume spike with OI being the dominant factor
+    if (oiBreakout && volumeBreakout && oiChange >= 0.2) {
+        return {
+            symbol,
+            tier: "FIRST_JUMP",
+            confidence: Math.min(oiChange * 3 + volumeRatio * 0.1, 1),
+            oiChange,
+            volumeRatio,
+        };
+    }
+    // CONTRIB_EXPLOSION: OI +15% AND volume 5x simultaneously
+    if (oiBreakout && volumeBreakout) {
+        return {
+            symbol,
+            tier: "CONTRIB_EXPLOSION",
+            confidence: Math.min(oiChange * 2.5 + volumeRatio * 0.08, 1),
+            oiChange,
+            volumeRatio,
+        };
+    }
+    // IMMEDIATE_MOVER: OI +15% OR volume 5x
+    if (oiBreakout || volumeBreakout) {
+        return {
+            symbol,
+            tier: "IMMEDIATE_MOVER",
+            confidence: Math.min(Math.max(oiChange * 2, volumeRatio * 0.15), 1),
+            oiChange,
+            volumeRatio,
+        };
+    }
+    // NEW_ENTRY_DEEP: OI growth 8%+ with low volume (smart money accumulation)
+    if (oiDeep && lowVolume) {
+        return {
+            symbol,
+            tier: "NEW_ENTRY_DEEP",
+            confidence: Math.min(oiChange * 3, 1),
+            oiChange,
+            volumeRatio,
+        };
+    }
+    // DEEP_CLIMBER: sustained OI climb 5%+ per window over 3+ consecutive scans
+    if (past.length >= 3) {
+        let consecutiveClimbs = 0;
+        for (let i = 1; i < past.length; i++) {
+            const prevOi = past[i - 1].oi;
+            const currOi = past[i].oi;
+            if (prevOi > 0 && (currOi - prevOi) / prevOi >= 0.05) {
+                consecutiveClimbs++;
+            }
+            else {
+                consecutiveClimbs = 0;
+            }
+        }
+        // Also check current vs last
+        if (prev.oi > 0 && oiChange >= 0.05)
+            consecutiveClimbs++;
+        if (consecutiveClimbs >= 3) {
+            return {
+                symbol,
+                tier: "DEEP_CLIMBER",
+                confidence: Math.min(consecutiveClimbs * 0.2, 1),
+                oiChange,
+                volumeRatio,
+            };
+        }
+    }
+    return { symbol, tier: "NONE", confidence: 0, oiChange, volumeRatio };
+}

package/dist/bot/apex/radar.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Radar: 4-stage scoring funnel (0-400 points)
+ * Stage 1: Market Structure (35%, 0-140) -- volume, OI, liquidity depth
+ * Stage 2: Technicals (30%, 0-120) -- RSI, EMA trend, pattern
+ * Stage 3: Funding (20%, 0-80) -- rate extremes, direction bias
+ * Stage 4: BTC Macro (15%, 0-60) -- BTC trend alignment, regime
+ */
+import type { EnrichedSnapshot } from "../strategy-types.js";
+export interface RadarScore {
+    symbol: string;
+    total: number;
+    structure: number;
+    technicals: number;
+    funding: number;
+    btcMacro: number;
+}
+export declare function scoreOpportunity(snapshot: EnrichedSnapshot, btcSnapshot: EnrichedSnapshot | null): RadarScore;

package/dist/bot/apex/radar.js

@@ -0,0 +1,150 @@
+/**
+ * Radar: 4-stage scoring funnel (0-400 points)
+ * Stage 1: Market Structure (35%, 0-140) -- volume, OI, liquidity depth
+ * Stage 2: Technicals (30%, 0-120) -- RSI, EMA trend, pattern
+ * Stage 3: Funding (20%, 0-80) -- rate extremes, direction bias
+ * Stage 4: BTC Macro (15%, 0-60) -- BTC trend alignment, regime
+ */
+import { calculateEMA, calculateRSI, detectRegime } from "../indicators.js";
+// ── Stage 1: Market Structure (0-140) ──
+function scoreStructure(snapshot) {
+    let score = 0;
+    // Volume component (0-50): higher 24h volume = more liquid
+    const vol = snapshot.volume24h;
+    if (vol > 100_000_000)
+        score += 50;
+    else if (vol > 50_000_000)
+        score += 40;
+    else if (vol > 10_000_000)
+        score += 30;
+    else if (vol > 1_000_000)
+        score += 15;
+    // OI component (0-50): higher open interest = more conviction
+    const oi = parseFloat(snapshot.openInterest);
+    if (oi > 50_000_000)
+        score += 50;
+    else if (oi > 20_000_000)
+        score += 40;
+    else if (oi > 5_000_000)
+        score += 25;
+    else if (oi > 1_000_000)
+        score += 10;
+    // Liquidity depth component (0-40): tight spread = deep book
+    const spread = snapshot.spreadPct;
+    if (spread < 0.01)
+        score += 40;
+    else if (spread < 0.03)
+        score += 30;
+    else if (spread < 0.05)
+        score += 20;
+    else if (spread < 0.1)
+        score += 10;
+    return Math.min(score, 140);
+}
+// ── Stage 2: Technicals (0-120) ──
+function scoreTechnicals(snapshot) {
+    let score = 0;
+    const klines = snapshot.klines;
+    if (klines.length < 20)
+        return 0;
+    const closes = klines.map(k => parseFloat(k.close));
+    // RSI component (0-40): extreme RSI = strong signal
+    const rsi = calculateRSI(closes, 14);
+    if (rsi <= 25 || rsi >= 75)
+        score += 40; // extreme
+    else if (rsi <= 30 || rsi >= 70)
+        score += 30; // strong
+    else if (rsi <= 35 || rsi >= 65)
+        score += 15; // moderate
+    // EMA trend alignment (0-40): price above EMA20 = bullish, below = bearish
+    const ema20 = calculateEMA(closes, 20);
+    const ema50 = calculateEMA(closes, Math.min(50, closes.length));
+    if (ema20.length > 0 && ema50.length > 0) {
+        const lastEma20 = ema20[ema20.length - 1];
+        const lastEma50 = ema50[ema50.length - 1];
+        const price = snapshot.price;
+        // Clear trend: price and short EMA aligned relative to long EMA
+        const bullTrend = price > lastEma20 && lastEma20 > lastEma50;
+        const bearTrend = price < lastEma20 && lastEma20 < lastEma50;
+        if (bullTrend || bearTrend)
+            score += 40;
+        else if (price > lastEma20 || price < lastEma20)
+            score += 15;
+    }
+    // Pattern component (0-40): recent volatility contraction then expansion
+    const recentVol = snapshot.volatility24h;
+    if (recentVol > 5)
+        score += 40; // high volatility breakout
+    else if (recentVol > 3)
+        score += 25;
+    else if (recentVol > 1.5)
+        score += 10;
+    return Math.min(score, 120);
+}
+// ── Stage 3: Funding (0-80) ──
+function scoreFunding(snapshot) {
+    let score = 0;
+    const fr = snapshot.fundingRate;
+    const absFr = Math.abs(fr);
+    // Extreme funding = contrarian opportunity (0-50)
+    if (absFr > 0.001)
+        score += 50; // >0.1% per period
+    else if (absFr > 0.0005)
+        score += 35; // >0.05%
+    else if (absFr > 0.0002)
+        score += 15; // >0.02%
+    // Direction bias bonus (0-30): extreme negative = long opportunity, extreme positive = short
+    if (fr < -0.0005)
+        score += 30; // heavy short bias → long signal
+    else if (fr > 0.0005)
+        score += 30; // heavy long bias → short signal
+    else if (absFr > 0.0002)
+        score += 10;
+    return Math.min(score, 80);
+}
+// ── Stage 4: BTC Macro (0-60) ──
+function scoreBtcMacro(btcSnapshot) {
+    if (!btcSnapshot)
+        return 30; // neutral if no BTC data
+    let score = 0;
+    const klines = btcSnapshot.klines;
+    if (klines.length < 20)
+        return 30;
+    const closes = klines.map(k => parseFloat(k.close));
+    const regime = detectRegime(closes, 20);
+    // Trending regime favors directional trades (0-35)
+    if (regime === "low-vol-trending")
+        score += 35;
+    else if (regime === "high-vol-trending")
+        score += 25;
+    else if (regime === "low-vol-ranging")
+        score += 10;
+    // high-vol-ranging = 0 (unfavorable)
+    // BTC trend alignment (0-25): clear BTC direction helps alts
+    const ema20 = calculateEMA(closes, 20);
+    if (ema20.length > 0) {
+        const btcPrice = btcSnapshot.price;
+        const lastEma = ema20[ema20.length - 1];
+        const pctAbove = (btcPrice - lastEma) / lastEma;
+        if (Math.abs(pctAbove) > 0.02)
+            score += 25; // strong BTC trend
+        else if (Math.abs(pctAbove) > 0.005)
+            score += 15; // moderate
+    }
+    return Math.min(score, 60);
+}
+// ── Main scorer ──
+export function scoreOpportunity(snapshot, btcSnapshot) {
+    const structure = scoreStructure(snapshot);
+    const technicals = scoreTechnicals(snapshot);
+    const funding = scoreFunding(snapshot);
+    const btcMacro = scoreBtcMacro(btcSnapshot);
+    return {
+        symbol: snapshot.klines[0]?.close ? "unknown" : "unknown", // caller sets symbol
+        total: structure + technicals + funding + btcMacro,
+        structure,
+        technicals,
+        funding,
+        btcMacro,
+    };
+}

package/dist/bot/conditions.d.ts

@@ -1,4 +1,4 @@
-import type { ExchangeAdapter } from "../exchanges/interface.js";
+import type { ExchangeAdapter } from "../exchanges/index.js";
 import type { Condition } from "./config.js";
 export interface MarketSnapshot {
     price: number;

package/dist/bot/config.d.ts

@@ -40,7 +40,11 @@ export interface FundingArbStrategyParams {
     max_positions: number;
     exchanges: string[];
 }
-export type StrategyParams = GridStrategyParams | DCAStrategyParams | FundingArbStrategyParams;
+export interface GenericStrategyParams {
+    type: string;
+    [key: string]: unknown;
+}
+export type StrategyParams = GridStrategyParams | DCAStrategyParams | FundingArbStrategyParams | GenericStrategyParams;
 export interface BotConfig {
     name: string;
     exchange: string;