perp-cli 0.7.48 → 0.9.1

package/dist/bot/engine.d.ts

@@ -19,6 +19,7 @@ import "./strategies/rfq-agent.js";
 import "./strategies/claude-agent.js";
 import "./strategies/apex-strategy.js";
 import "./strategies/funding-auto.js";
+import "./strategies/spot-perp-arb-strategy.js";
 export type BotLog = (msg: string) => void;
 export type BotOutputMode = "tui" | "json" | "headless";
 export declare function runBot(adapter: ExchangeAdapter, config: BotConfig, jobId?: string, log?: BotLog, extraAdapters?: Map<string, ExchangeAdapter>, // for funding-arb (multi-exchange)

package/dist/bot/engine.js

@@ -22,6 +22,7 @@ import "./strategies/rfq-agent.js";
 import "./strategies/claude-agent.js";
 import "./strategies/apex-strategy.js";
 import "./strategies/funding-auto.js";
+import "./strategies/spot-perp-arb-strategy.js";
 // ── TUI state emitter ──
 class TuiEmitter {
     stateListeners = [];

package/dist/bot/strategies/funding-arb-strategy.js

@@ -201,12 +201,21 @@ export class FundingArbStrategy {
                 const equity = parseFloat(bal.equity);
                 const marginUsed = parseFloat(bal.marginUsed);
                 const marginPct = equity > 0 ? (marginUsed / equity) * 100 : 100;
-                exchangeBalances.set(name, { equity, available: parseFloat(bal.available), marginPct });
-                if (marginPct < 90) {
-                    availableAdapters.set(name, a);
+                const available = parseFloat(bal.available);
+                exchangeBalances.set(name, { equity, available, marginPct });
+                // Skip if: margin > 90%, available < $5, or exchange on liquidation cooldown
+                const exchCooldown = this._failCooldown.get(`${name}:exchange`) ?? 0;
+                if (Date.now() < exchCooldown) {
+                    ctx.log(`  [ARB] ${name} on liquidation cooldown — skipping`);
+                }
+                else if (available < 5) {
+                    ctx.log(`  [ARB] ${name} available $${available.toFixed(2)} too low — skipping`);
+                }
+                else if (marginPct >= 90) {
+                    ctx.log(`  [ARB] ${name} margin ${marginPct.toFixed(0)}% — skipping`);
                 }
                 else {
-                    ctx.log(`  [ARB] ${name} margin ${marginPct.toFixed(0)}% — skipping for this tick`);
+                    availableAdapters.set(name, a);
                 }
             }
             catch (err) {
@@ -315,8 +324,8 @@ export class FundingArbStrategy {
             // Close if funding flipped (losing money) or spread below close threshold
             const minHoldMs = (params.min_hold_hours ?? 2) * 60 * 60 * 1000;
             const holdTime = pos.entryTime > 0 ? Date.now() - pos.entryTime : Infinity;
-            const isFundingFlipped = signedSpread < 0;
-            const shouldClose = isFundingFlipped || (holdTime >= minHoldMs && signedSpread < params.close_spread);
+            const deeplyNegative = signedSpread < -20; // urgent: losing significant funding
+            const shouldClose = deeplyNegative || (holdTime >= minHoldMs && signedSpread < params.close_spread);
             if (shouldClose) {
                 // Cooldown: skip if close recently failed for this symbol
                 const closeKey = `${pos.symbol}:close`;
@@ -348,6 +357,8 @@ export class FundingArbStrategy {
                                 // Position already liquidated/closed on this exchange
                                 longPositionGone = true;
                                 ctx.log(`  [ARB] Long position gone for ${pos.symbol} on ${pos.longExchange} (liquidated?) — force closing short`);
+                                // Cooldown the exchange for 30 minutes to prevent liquidation-entry cycle
+                                this._failCooldown.set(`${pos.longExchange}:exchange`, Date.now() + 30 * 60 * 1000);
                             }
                             else {
                                 ctx.log(`  [ARB] Close long leg failed for ${pos.symbol}: ${msg} (cooldown 5m)`);
@@ -366,6 +377,7 @@ export class FundingArbStrategy {
                             if (isPositionGone(msg)) {
                                 // Short position also gone — both liquidated, just clean up tracking
                                 ctx.log(`  [ARB] Short position also gone for ${pos.symbol} on ${pos.shortExchange} — removing from tracking`);
+                                this._failCooldown.set(`${pos.shortExchange}:exchange`, Date.now() + 30 * 60 * 1000);
                             }
                             else if (closeLongOk) {
                                 // Long was closed but short failed (not liquidated) — rollback long
@@ -623,20 +635,7 @@ export class FundingArbStrategy {
                             const rbMsg = rbErr instanceof Error ? rbErr.message : String(rbErr);
                             ctx.log(`  [ARB] CRITICAL: Rollback failed for ${best.symbol}: ${rbMsg}`);
                             logExecution({ type: "multi_leg_rollback", exchange: best.longExchange, symbol: best.symbol, side: "sell", size: matched.size, status: "failed", error: rbMsg, dryRun: false });
-                            // Track orphaned long position for manual cleanup
-                            const currentPositions = ctx.state.get("arbOpenPositions");
-                            currentPositions.push({
-                                symbol: best.symbol,
-                                longExchange: best.longExchange,
-                                shortExchange: best.shortExchange, // note: short leg doesn't exist
-                                entrySpread: 0,
-                                size: matched.size,
-                                mode: "perp-perp",
-                                entryTime: 0, // flag as orphaned
-                            });
-                            ctx.state.set("arbOpenPositions", currentPositions);
-                            ctx.state.set("arbPositions", currentPositions.length);
-                            ctx.log(`  [ARB] Tracking orphaned long position for manual cleanup`);
+                            ctx.log(`  [ARB] CRITICAL: Orphaned long position on ${best.longExchange} for ${best.symbol} — operator must close manually`);
                         }
                         this._failCooldown.set(`${best.symbol}:entry`, Date.now() + 5 * 60 * 1000);
                         continue;
@@ -979,6 +978,11 @@ export class FundingArbStrategy {
                 const msg = spotErr instanceof Error ? spotErr.message : String(spotErr);
                 ctx.log(`  [ARB] Open spot-perp failed (spot buy) for ${opp.symbol}: ${msg}`);
                 logExecution({ type: "arb_entry", exchange: opp.longExchange, symbol: opp.symbol, side: "buy", size: matched.size, status: "failed", error: msg, dryRun: false, meta: { mode: "spot-perp", leg: "spot" } });
+                try {
+                    await this.transferUsdcToPerp(spotAdapter, exchangeName, transferAmt);
+                    ctx.log(`  [ARB] Transferred $${transferAmt} USDC back to perp after spot buy failure`);
+                }
+                catch { /* best effort */ }
                 return false;
             }
             // Step 3: Short perp
@@ -1143,9 +1147,12 @@ export class FundingArbStrategy {
             // Bootstrap aster funding hours lazily (1 API call per unknown symbol, cached permanently)
             if (exchangeName === "aster" && "getFundingHours" in adapter) {
                 const aster = adapter;
-                // Only bootstrap symbols not yet cached (up to 5 per tick to limit API calls)
-                const uncached = withRates.filter(m => m.fundingHours === undefined || m.fundingHours === 1);
-                const toBootstrap = uncached.slice(0, 5);
+                // Only bootstrap symbols not yet cached (up to 20 per tick to complete faster)
+                const uncached = withRates.filter(m => {
+                    const cached = adapter?._fundingHoursCache?.get?.(m.symbol);
+                    return cached === undefined; // only truly uncached, not symbols confirmed as 1h
+                });
+                const toBootstrap = uncached.slice(0, 20);
                 for (const m of toBootstrap) {
                     const fh = await aster.getFundingHours(m.symbol);
                     m.fundingHours = fh;

package/dist/bot/strategies/funding-arb-utils.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Shared utilities for funding arbitrage strategies (v1 + v2).
+ * Extracted to keep individual strategy files under size limits.
+ */
+import type { StrategyContext } from "../strategy-types.js";
+import type { ExchangeAdapter } from "../../exchanges/index.js";
+import type { SpotAdapter } from "../../exchanges/spot-interface.js";
+export type RateEntry = {
+    rate: number;
+    price: number;
+    sizeDecimals?: number;
+    maxLeverage?: number;
+    fundingHours?: number;
+};
+export type RateMap = Map<string, Map<string, RateEntry>>;
+/** Build adapter map from primary adapter + extraAdapters in context state. */
+export declare function buildAdapterMap(ctx: StrategyContext): Map<string, ExchangeAdapter>;
+/** Get or create a spot adapter for a given exchange name + perp adapter instance. */
+export declare function getSpotAdapter(name: string, adapter: ExchangeAdapter): Promise<SpotAdapter | null>;
+/** Transfer USDC from perp to spot account (exchange-specific). */
+export declare function transferUsdcToSpot(spotAdapter: SpotAdapter, exchangeName: string, amount: number): Promise<void>;
+/** Transfer USDC from spot to perp account (exchange-specific). */
+export declare function transferUsdcToPerp(spotAdapter: SpotAdapter, exchangeName: string, amount: number): Promise<void>;
+/** Resolve perp symbol for a given base symbol on an exchange. */
+export declare function getPerpSymbol(baseSymbol: string, _exchangeName: string): string;
+/** Look up rate from ratesByExchange, trying symbol, symbol-PERP, and symbol without -PERP. */
+export declare function findRate(ratesByExchange: RateMap, exchange: string, symbol: string): RateEntry | undefined;
+/** Match a symbol against a target, accounting for -PERP suffix variations. */
+export declare function matchSymbol(s: string, target: string): boolean;
+/** Get a price estimate for a symbol from the perp adapter. */
+export declare function getPriceEstimate(perpAdapter: ExchangeAdapter, perpSymbol: string, fallbackSymbol: string): Promise<number>;
+export interface RecoveredPosition {
+    symbol: string;
+    mode: "spot-perp" | "perp-perp";
+    longExchange: string;
+    shortExchange: string;
+    size: string;
+}
+/** Recover arb positions from exchange state (perp-perp + spot-perp, same + cross exchange). */
+export declare function recoverArbPositions(adapters: Map<string, ExchangeAdapter>, log: (msg: string) => void): Promise<RecoveredPosition[]>;
+/** Fetch funding rates from an exchange adapter. */
+export declare function fetchRates(adapter: ExchangeAdapter, exchangeName: string): Promise<{
+    symbol: string;
+    rate: number;
+    price: number;
+    sizeDecimals?: number;
+    maxLeverage?: number;
+    fundingHours?: number;
+}[]>;

package/dist/bot/strategies/funding-arb-utils.js

@@ -0,0 +1,239 @@
+/**
+ * Shared utilities for funding arbitrage strategies (v1 + v2).
+ * Extracted to keep individual strategy files under size limits.
+ */
+// ── Adapter helpers ──
+/** Build adapter map from primary adapter + extraAdapters in context state. */
+export function buildAdapterMap(ctx) {
+    const extraAdapters = ctx.state.get("extraAdapters");
+    const adapters = new Map();
+    adapters.set(ctx.adapter.name.toLowerCase(), ctx.adapter);
+    if (extraAdapters) {
+        for (const [name, a] of extraAdapters)
+            adapters.set(name, a);
+    }
+    return adapters;
+}
+const spotAdapterCache = new Map();
+/** Get or create a spot adapter for a given exchange name + perp adapter instance. */
+export async function getSpotAdapter(name, adapter) {
+    const cached = spotAdapterCache.get(name);
+    if (cached)
+        return cached;
+    try {
+        let spot = null;
+        if (name === "hyperliquid") {
+            const { HyperliquidSpotAdapter } = await import("../../exchanges/hyperliquid-spot.js");
+            const { HyperliquidAdapter } = await import("../../exchanges/hyperliquid.js");
+            if (adapter instanceof HyperliquidAdapter) {
+                const instance = new HyperliquidSpotAdapter(adapter);
+                await instance.init();
+                spot = instance;
+            }
+        }
+        else if (name === "lighter") {
+            const { LighterSpotAdapter } = await import("../../exchanges/lighter-spot.js");
+            const { LighterAdapter } = await import("../../exchanges/lighter.js");
+            if (adapter instanceof LighterAdapter) {
+                const instance = new LighterSpotAdapter(adapter);
+                await instance.init();
+                spot = instance;
+            }
+        }
+        if (spot)
+            spotAdapterCache.set(name, spot);
+        return spot;
+    }
+    catch { /* not supported */ }
+    return null;
+}
+// ── Transfer helpers ──
+/** Transfer USDC from perp to spot account (exchange-specific). */
+export async function transferUsdcToSpot(spotAdapter, exchangeName, amount) {
+    if (exchangeName === "hyperliquid") {
+        const { HyperliquidSpotAdapter } = await import("../../exchanges/hyperliquid-spot.js");
+        if (spotAdapter instanceof HyperliquidSpotAdapter) {
+            await spotAdapter.transferUsdcToSpot(amount);
+            return;
+        }
+    }
+    else if (exchangeName === "lighter") {
+        const { LighterSpotAdapter } = await import("../../exchanges/lighter-spot.js");
+        if (spotAdapter instanceof LighterSpotAdapter) {
+            await spotAdapter.transferUsdcToSpot(amount);
+            return;
+        }
+    }
+}
+/** Transfer USDC from spot to perp account (exchange-specific). */
+export async function transferUsdcToPerp(spotAdapter, exchangeName, amount) {
+    if (exchangeName === "hyperliquid") {
+        const { HyperliquidSpotAdapter } = await import("../../exchanges/hyperliquid-spot.js");
+        if (spotAdapter instanceof HyperliquidSpotAdapter) {
+            await spotAdapter.transferUsdcToPerp(amount);
+            return;
+        }
+    }
+    else if (exchangeName === "lighter") {
+        const { LighterSpotAdapter } = await import("../../exchanges/lighter-spot.js");
+        if (spotAdapter instanceof LighterSpotAdapter) {
+            await spotAdapter.transferUsdcToPerp(amount);
+            return;
+        }
+    }
+}
+// ── Rate / symbol helpers ──
+/** Resolve perp symbol for a given base symbol on an exchange. */
+export function getPerpSymbol(baseSymbol, _exchangeName) {
+    return baseSymbol.replace(/-PERP$/, "").toUpperCase();
+}
+/** Look up rate from ratesByExchange, trying symbol, symbol-PERP, and symbol without -PERP. */
+export function findRate(ratesByExchange, exchange, symbol) {
+    const map = ratesByExchange.get(exchange);
+    if (!map)
+        return undefined;
+    const upper = symbol.toUpperCase();
+    return map.get(upper) ?? map.get(upper + "-PERP") ?? map.get(upper.replace(/-PERP$/, ""));
+}
+/** Match a symbol against a target, accounting for -PERP suffix variations. */
+export function matchSymbol(s, target) {
+    const u = s.toUpperCase();
+    const t = target.toUpperCase();
+    return u === t || u === t + "-PERP" || u.replace(/-PERP$/, "") === t;
+}
+/** Get a price estimate for a symbol from the perp adapter. */
+export async function getPriceEstimate(perpAdapter, perpSymbol, fallbackSymbol) {
+    try {
+        const markets = await perpAdapter.getMarkets();
+        const market = markets.find(m => m.symbol.toUpperCase() === perpSymbol.toUpperCase() ||
+            m.symbol.toUpperCase() === fallbackSymbol.toUpperCase() ||
+            m.symbol.toUpperCase() === `${fallbackSymbol.toUpperCase()}-PERP`);
+        return market ? parseFloat(market.markPrice) : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+/** Recover arb positions from exchange state (perp-perp + spot-perp, same + cross exchange). */
+export async function recoverArbPositions(adapters, log) {
+    const positionsByExchange = new Map();
+    for (const [name, a] of adapters) {
+        try {
+            const positions = await a.getPositions();
+            positionsByExchange.set(name, positions.map(p => ({ symbol: p.symbol.toUpperCase(), side: p.side, size: p.size })));
+        }
+        catch { /* skip */ }
+    }
+    const recovered = [];
+    const used = new Set();
+    // Cross-exchange perp-perp
+    for (const [exA, posA] of positionsByExchange) {
+        for (const pA of posA) {
+            const keyA = `${exA}:${pA.symbol}`;
+            if (used.has(keyA))
+                continue;
+            for (const [exB, posB] of positionsByExchange) {
+                if (exA === exB)
+                    continue;
+                for (const pB of posB) {
+                    const keyB = `${exB}:${pB.symbol}`;
+                    if (used.has(keyB) || pA.symbol !== pB.symbol || pA.side === pB.side)
+                        continue;
+                    const longEx = pA.side === "long" ? exA : exB;
+                    const shortEx = pA.side === "short" ? exA : exB;
+                    recovered.push({ symbol: pA.symbol, mode: "perp-perp", longExchange: longEx, shortExchange: shortEx, size: pA.side === "long" ? pA.size : pB.size });
+                    used.add(keyA);
+                    used.add(keyB);
+                    break;
+                }
+                if (used.has(keyA))
+                    break;
+            }
+        }
+    }
+    // Same-exchange spot-perp hedges
+    for (const [name, a] of adapters) {
+        try {
+            const spotAdapter = await getSpotAdapter(name, a);
+            if (!spotAdapter)
+                continue;
+            const bals = await spotAdapter.getSpotBalances();
+            const nonUsdc = bals.filter(b => Number(b.total) > 0 && !b.token.toUpperCase().startsWith("USDC"));
+            if (nonUsdc.length === 0)
+                continue;
+            for (const perp of positionsByExchange.get(name) ?? []) {
+                const perpKey = `${name}:${perp.symbol}`;
+                if (used.has(perpKey))
+                    continue;
+                const base = perp.symbol.replace(/-PERP$/, "").toUpperCase();
+                const spotBal = nonUsdc.find(b => b.token.toUpperCase().replace(/-SPOT$/, "") === base);
+                if (spotBal && perp.side === "short") {
+                    recovered.push({ symbol: base, mode: "spot-perp", longExchange: `${name}-spot`, shortExchange: name, size: perp.size });
+                    used.add(perpKey);
+                    log(`  Recovered spot-perp: ${base} ${name}-spot<>${name}`);
+                }
+            }
+        }
+        catch { /* no spot */ }
+    }
+    // Cross-exchange spot-perp
+    for (const [spotExName, spotExAdapter] of adapters) {
+        try {
+            const spotAdapter = await getSpotAdapter(spotExName, spotExAdapter);
+            if (!spotAdapter)
+                continue;
+            const bals = await spotAdapter.getSpotBalances();
+            const nonUsdc = bals.filter(b => Number(b.total) > 0 && !b.token.toUpperCase().startsWith("USDC"));
+            for (const bal of nonUsdc) {
+                const base = bal.token.toUpperCase().replace(/-SPOT$/, "");
+                for (const [perpExName, perpPositions] of positionsByExchange) {
+                    if (perpExName === spotExName)
+                        continue;
+                    for (const perp of perpPositions) {
+                        const perpKey = `${perpExName}:${perp.symbol}`;
+                        if (used.has(perpKey))
+                            continue;
+                        if (perp.symbol.replace(/-PERP$/, "").toUpperCase() === base && perp.side === "short") {
+                            recovered.push({ symbol: base, mode: "spot-perp", longExchange: `${spotExName}-spot`, shortExchange: perpExName, size: perp.size });
+                            used.add(perpKey);
+                            log(`  Recovered cross spot-perp: ${base} ${spotExName}-spot<>${perpExName}`);
+                        }
+                    }
+                }
+            }
+        }
+        catch { /* no spot */ }
+    }
+    return recovered;
+}
+/** Fetch funding rates from an exchange adapter. */
+export async function fetchRates(adapter, exchangeName) {
+    try {
+        const markets = await adapter.getMarkets();
+        const withRates = markets.filter(m => m.fundingRate != null);
+        // Bootstrap aster funding hours lazily
+        if (exchangeName === "aster" && "getFundingHours" in adapter) {
+            const aster = adapter;
+            const uncached = withRates.filter(m => {
+                const c = adapter?._fundingHoursCache?.get?.(m.symbol);
+                return c === undefined;
+            });
+            for (const m of uncached.slice(0, 20)) {
+                m.fundingHours = await aster.getFundingHours(m.symbol);
+            }
+        }
+        return withRates
+            .filter(m => m.fundingHours != null) // skip symbols with unknown funding period (aster not yet bootstrapped)
+            .map(m => ({
+            symbol: m.symbol,
+            rate: parseFloat(m.fundingRate),
+            price: parseFloat(m.markPrice),
+            sizeDecimals: m.sizeDecimals,
+            maxLeverage: m.maxLeverage,
+            fundingHours: m.fundingHours,
+        }));
+    }
+    catch {
+        return [];
+    }
+}

package/dist/bot/strategies/funding-arb-v2-strategy.d.ts

@@ -0,0 +1,42 @@
+import type { Strategy, StrategyContext, StrategyAction, EnrichedSnapshot } from "../strategy-types.js";
+export declare class FundingArbV2Strategy implements Strategy {
+    readonly name = "funding-arb-v2";
+    describe(): {
+        description: string;
+        params: ({
+            name: string;
+            type: "number";
+            required: boolean;
+            default: number;
+            description: string;
+        } | {
+            name: string;
+            type: "string";
+            required: boolean;
+            description: string;
+            default?: undefined;
+        } | {
+            name: string;
+            type: "boolean";
+            required: boolean;
+            default: boolean;
+            description: string;
+        })[];
+    };
+    private _config;
+    private _failCooldown;
+    private _fundingScoreCache;
+    private get params();
+    init(ctx: StrategyContext, _snapshot: EnrichedSnapshot): Promise<void>;
+    onTick(ctx: StrategyContext, _snapshot: EnrichedSnapshot): Promise<StrategyAction[]>;
+    onStop(ctx: StrategyContext): Promise<StrategyAction[]>;
+    private scoreFunding;
+    private calcSignedSpread;
+    private checkCloseByHistory;
+    private findBestPerpShort;
+    private rotateShort;
+    private openSpotPerp;
+    private closeSpotPerp;
+    private openPerpPerp;
+    private closePerpPerp;
+}