perp-cli 0.12.15 → 0.14.0

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

@@ -4,7 +4,15 @@
  */
 import type { StrategyContext } from "../strategy-types.js";
 import type { ExchangeAdapter } from "../../exchanges/index.js";
-import type { SpotAdapter } from "../../exchanges/spot-interface.js";
+import type { SpotAdapter, SpotMarketInfo } from "../../exchanges/spot-interface.js";
+import type { VenueMarket } from "../../exchanges/venue-types.js";
+import "../../exchanges/venues/index.js";
+/**
+ * Funding strategies refuse a venue whose funding rate is unverified as a leg (design §14.12
+ * #6): every adapter of the run (primary + extraAdapters) is checked when the strategy starts.
+ * Adapter names that are not registered venues (test doubles) are not venues and are skipped.
+ */
+export declare function assertFundingArbLegs(ctx: StrategyContext): void;
 export type RateEntry = {
     rate: number;
     price: number;
@@ -15,12 +23,26 @@ export type RateEntry = {
 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>;
+/**
+ * Move the spot venue's quote asset (quoteAssets[0]) perp → spot. Returns false when
+ * spot shares perp margin (no-op — callers must not log "Transferred"); throws when
+ * the venue has no transfer.
+ */
+export declare function transferUsdcToSpot(spotAdapter: SpotAdapter, amount: number): Promise<boolean>;
+/** Spot → perp counterpart of transferUsdcToSpot. */
+export declare function transferUsdcToPerp(spotAdapter: SpotAdapter, amount: number): Promise<boolean>;
+/**
+ * Bot spot↔perp candidates: spot bases on `spotVenue` matched to each perp venue by
+ * canonical symbol + price-deviation guard (`matchSpotPerp`). Bare-ticker equality is
+ * not enough. Bot positions store one symbol and derive the perp leg with
+ * `getPerpSymbol(base)`, so a canonical pair whose perp symbol differs from the spot
+ * base (e.g. UBTC ↔ BTC) is reported and skipped rather than traded under the wrong
+ * perp symbol. Returns perp venue → matched spot bases (upper-case).
+ *
+ * `perpMarketsCache` lets one scan reuse each perp venue's public market fetch.
+ * A perp venue whose markets cannot be fetched is logged and gets no candidates.
+ */
+export declare function botSpotPerpMatches(spotVenue: string, spotMarkets: readonly SpotMarketInfo[], perpVenues: readonly string[], perpMarketsCache: Map<string, Promise<VenueMarket[]>>, log: (msg: string) => void): Promise<Map<string, Set<string>>>;
 /** 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. */
@@ -29,15 +51,6 @@ export declare function findRate(ratesByExchange: RateMap, exchange: string, sym
 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[]>;
 export interface FundingScore {
     symbol: string;
     exchange: string;
@@ -46,18 +59,24 @@ export interface FundingScore {
     annualized: number;
     payments: number;
 }
-/** Returns true if a reduceOnly rejection indicates the position is already gone. */
-export declare function isPositionGone(msg: string): boolean;
-/** Compute funding period in hours from history timestamps. Falls back to static map. */
-export declare function computeFundingHoursFromHistory(history: {
-    time: number;
-}[]): number;
+/**
+ * true when a reduce-only close was rejected because there is no position left to reduce.
+ * Prefers the typed signal: placePerpVerified's ORDER_REJECTED with details.reduceOnlyFlat
+ * (flat before and after the order — "(no X position to reduce)"). Venue texts that carry the
+ * same meaning are matched too: HL "Reduce only order would increase position", Aster -2022
+ * / "ReduceOnly Order is rejected". Only ever applied to a DEFINITE rejection (an
+ * ORDER_PENDING outcome is never "gone").
+ */
+export declare function isPositionGone(e: unknown): boolean;
 /** Score a symbol's funding rate using history. Returns null if insufficient data. */
 export declare function scoreFunding(adapter: ExchangeAdapter, symbol: string, exchangeName: string, periods: number, cache?: Map<string, {
     score: FundingScore;
     ts: number;
 }>): Promise<FundingScore | null>;
-/** Fetch funding rates from an exchange adapter. */
+/**
+ * Fetch funding rates from an exchange adapter. Failures propagate — callers
+ * record them per venue (an empty list would read as "venue has no markets").
+ */
 export declare function fetchRates(adapter: ExchangeAdapter, exchangeName: string): Promise<{
     symbol: string;
     rate: number;
@@ -66,3 +85,9 @@ export declare function fetchRates(adapter: ExchangeAdapter, exchangeName: strin
     maxLeverage?: number;
     fundingHours?: number;
 }[]>;
+/**
+ * Cancel the open orders of `symbols` (the bot's own) on every venue in `adapters` — never an
+ * account-wide cancel. Each failure is logged (never "cancelled"); nothing is logged as
+ * cancelled when the bot traded no symbol.
+ */
+export declare function cancelBotSymbols(adapters: Map<string, ExchangeAdapter>, symbols: ReadonlySet<string>, tag: string, log: (msg: string) => void): Promise<void>;

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

@@ -3,7 +3,29 @@
  * Extracted to keep individual strategy files under size limits.
  */
 import { getFundingHours } from "../../funding.js";
+import { sharedApiNetwork } from "../../api/public/urls.js";
 import { annualizeHourlyRate } from "../../funding/normalize.js";
+import { fetchPerpMarketsForMatching, matchSpotPerp, transferQuoteToPerp, transferQuoteToSpot } from "../../exchanges/spot-factory.js";
+import { PerpError, extractErrorMessage } from "../../errors.js";
+import { assertFundingArbVenue, tryResolveVenueId } from "../../exchanges/venue.js";
+import "../../exchanges/venues/index.js";
+/**
+ * Funding strategies refuse a venue whose funding rate is unverified as a leg (design §14.12
+ * #6): every adapter of the run (primary + extraAdapters) is checked when the strategy starts.
+ * Adapter names that are not registered venues (test doubles) are not venues and are skipped.
+ */
+export function assertFundingArbLegs(ctx) {
+    const names = new Set([ctx.adapter.name]);
+    const extra = ctx.state.get("extraAdapters");
+    if (extra !== undefined)
+        for (const a of extra.values())
+            names.add(a.name);
+    for (const name of names) {
+        if (tryResolveVenueId(name.split(":")[0]) === null)
+            continue;
+        assertFundingArbVenue(name);
+    }
+}
 // ── Adapter helpers ──
 /** Build adapter map from primary adapter + extraAdapters in context state. */
 export function buildAdapterMap(ctx) {
@@ -16,73 +38,64 @@ export function buildAdapterMap(ctx) {
     }
     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 (§12.4 #4) ──
+// Spot adapters come from the factory (src/exchanges/spot-factory.ts, getBotSpotAdapter).
+/**
+ * Move the spot venue's quote asset (quoteAssets[0]) perp → spot. Returns false when
+ * spot shares perp margin (no-op — callers must not log "Transferred"); throws when
+ * the venue has no transfer.
+ */
+export async function transferUsdcToSpot(spotAdapter, amount) {
+    return transferQuoteToSpot(spotAdapter, amount);
 }
-// ── 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;
+/** Spot → perp counterpart of transferUsdcToSpot. */
+export async function transferUsdcToPerp(spotAdapter, amount) {
+    return transferQuoteToPerp(spotAdapter, amount);
+}
+// ── Spot ↔ perp matching (§12.4 #6) ──
+/**
+ * Bot spot↔perp candidates: spot bases on `spotVenue` matched to each perp venue by
+ * canonical symbol + price-deviation guard (`matchSpotPerp`). Bare-ticker equality is
+ * not enough. Bot positions store one symbol and derive the perp leg with
+ * `getPerpSymbol(base)`, so a canonical pair whose perp symbol differs from the spot
+ * base (e.g. UBTC ↔ BTC) is reported and skipped rather than traded under the wrong
+ * perp symbol. Returns perp venue → matched spot bases (upper-case).
+ *
+ * `perpMarketsCache` lets one scan reuse each perp venue's public market fetch.
+ * A perp venue whose markets cannot be fetched is logged and gets no candidates.
+ */
+export async function botSpotPerpMatches(spotVenue, spotMarkets, perpVenues, perpMarketsCache, log) {
+    const out = new Map();
+    for (const perpVenue of perpVenues) {
+        let pending = perpMarketsCache.get(perpVenue);
+        if (pending === undefined) {
+            pending = fetchPerpMarketsForMatching(perpVenue);
+            perpMarketsCache.set(perpVenue, pending);
         }
-    }
-    else if (exchangeName === "lighter") {
-        const { LighterSpotAdapter } = await import("../../exchanges/lighter-spot.js");
-        if (spotAdapter instanceof LighterSpotAdapter) {
-            await spotAdapter.transferUsdcToSpot(amount);
-            return;
+        let perpMarkets;
+        try {
+            perpMarkets = await pending;
         }
-    }
-}
-/** 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;
+        catch (e) {
+            log(`spot↔perp matching: ${perpVenue} perp markets unavailable (${e instanceof Error ? e.message : String(e)}) — no ${perpVenue} candidates this scan`);
+            out.set(perpVenue, new Set());
+            continue;
         }
-    }
-    else if (exchangeName === "lighter") {
-        const { LighterSpotAdapter } = await import("../../exchanges/lighter-spot.js");
-        if (spotAdapter instanceof LighterSpotAdapter) {
-            await spotAdapter.transferUsdcToPerp(amount);
-            return;
+        const matches = matchSpotPerp(spotVenue, spotMarkets, perpVenue, perpMarkets, log, sharedApiNetwork());
+        const bases = new Set();
+        const aliased = [];
+        for (const m of matches.values()) {
+            if (getPerpSymbol(m.spotBase, perpVenue) === m.perpSymbol.toUpperCase())
+                bases.add(m.spotBase);
+            else
+                aliased.push(`${m.spotBase}↔${m.perpSymbol}`);
+        }
+        if (aliased.length > 0) {
+            log(`spot↔perp matching ${spotVenue}→${perpVenue}: ${aliased.length} canonical pair(s) with a different perp symbol skipped (bot positions use one symbol): ${aliased.join(", ")}`);
         }
+        out.set(perpVenue, bases);
     }
+    return out;
 }
 // ── Rate / symbol helpers ──
 /** Resolve perp symbol for a given base symbol on an exchange. */
@@ -116,112 +129,41 @@ export async function getPriceEstimate(perpAdapter, perpSymbol, fallbackSymbol)
         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;
+/**
+ * true when a reduce-only close was rejected because there is no position left to reduce.
+ * Prefers the typed signal: placePerpVerified's ORDER_REJECTED with details.reduceOnlyFlat
+ * (flat before and after the order — "(no X position to reduce)"). Venue texts that carry the
+ * same meaning are matched too: HL "Reduce only order would increase position", Aster -2022
+ * / "ReduceOnly Order is rejected". Only ever applied to a DEFINITE rejection (an
+ * ORDER_PENDING outcome is never "gone").
+ */
+export function isPositionGone(e) {
+    if (e instanceof PerpError) {
+        if (e.structured.code === "ORDER_PENDING")
+            return false;
+        if (e.structured.code === "ORDER_REJECTED" && e.structured.details?.reduceOnlyFlat === true)
+            return true;
+    }
+    const msg = typeof e === "string" ? e : extractErrorMessage(e);
+    return /position to reduce\)/.test(msg)
+        || /reduce only order would increase position/i.test(msg)
+        || msg.includes("ReduceOnly") || msg.includes("reduceOnly") || msg.includes("-2022");
 }
-/** Returns true if a reduceOnly rejection indicates the position is already gone. */
-export function isPositionGone(msg) {
-    return msg.includes("ReduceOnly") || msg.includes("reduceOnly") || msg.includes("-2022");
+function hasPerSymbolFundingHours(adapter) {
+    return typeof adapter.getFundingHours === "function";
 }
-/** Compute funding period in hours from history timestamps. Falls back to static map. */
-export function computeFundingHoursFromHistory(history) {
-    if (history.length < 2)
-        return getFundingHours("unknown"); // fallback to 1
-    const times = history.map(h => h.time).sort((a, b) => a - b);
-    let totalInterval = 0;
-    for (let i = 1; i < times.length; i++)
-        totalInterval += times[i] - times[i - 1];
-    const avgIntervalH = totalInterval / (times.length - 1) / 3600000;
-    return avgIntervalH < 1.5 ? 1 : avgIntervalH < 5 ? 4 : 8;
+/**
+ * Funding basis (hours one quoted rate covers) for a market: the market's own
+ * value when the venue publishes one per symbol, else the venue definition.
+ * History timestamp spacing is settlement timing, never the basis (§10.13 #2).
+ * @returns null when the venue publishes per-symbol values and this symbol has none
+ */
+async function marketFundingHours(adapter, exchangeName, symbol) {
+    if (hasPerSymbolFundingHours(adapter)) {
+        const hours = await adapter.getFundingHours(symbol);
+        return hours === undefined ? null : hours;
+    }
+    return getFundingHours(exchangeName);
 }
 /** Score a symbol's funding rate using history. Returns null if insufficient data. */
 export async function scoreFunding(adapter, symbol, exchangeName, periods, cache) {
@@ -229,12 +171,16 @@ export async function scoreFunding(adapter, symbol, exchangeName, periods, cache
     const cached = cache?.get(key);
     if (cached && Date.now() - cached.ts < 10 * 60 * 1000)
         return cached.score;
+    // Outside the try: an unknown venue is a configuration error, not "no score".
+    const venueHours = hasPerSymbolFundingHours(adapter) ? null : getFundingHours(exchangeName);
     try {
+        const fH = venueHours !== null ? venueHours : await marketFundingHours(adapter, exchangeName, symbol);
+        if (fH === null)
+            return null; // per-symbol basis unknown — the hourly rate would be a guess
         const history = await adapter.getFundingHistory(symbol, periods);
         if (history.length < 2)
             return null;
         const rates = history.map(h => parseFloat(h.rate));
-        const fH = computeFundingHoursFromHistory(history);
         const avgRate = rates.reduce((s, r) => s + r, 0) / rates.length;
         const consistency = rates.filter(r => r > 0).length / rates.length;
         const annualized = annualizeHourlyRate(avgRate / fH);
@@ -246,42 +192,60 @@ export async function scoreFunding(adapter, symbol, exchangeName, periods, cache
         return null;
     }
 }
-/** Fetch funding rates from an exchange adapter. */
+/**
+ * Fetch funding rates from an exchange adapter. Failures propagate — callers
+ * record them per venue (an empty list would read as "venue has no markets").
+ */
 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);
-            }
-        }
-        // For non-aster exchanges, set fundingHours from static map if not already set
-        if (exchangeName !== "aster") {
-            const defaultFH = getFundingHours(exchangeName);
-            for (const m of withRates) {
-                if (m.fundingHours == null)
-                    m.fundingHours = defaultFH;
-            }
-        }
-        return withRates
-            .filter(m => m.fundingHours != null) // skip aster symbols with unknown funding period
-            .map(m => ({
+    const markets = await adapter.getMarkets();
+    const withRates = markets.filter(m => m.fundingRate != null);
+    // fundingHours = basis (§10.13 #7): market value first, then the venue definition.
+    // Per-symbol venues (Aster) load their whole table in one call; symbols it
+    // does not list stay null and are skipped below.
+    for (const m of withRates) {
+        if (m.fundingHours !== null)
+            continue;
+        m.fundingHours = await marketFundingHours(adapter, exchangeName, m.symbol);
+    }
+    const result = [];
+    for (const m of withRates) {
+        // Skip aster symbols with unknown funding period — the hourly rate would be a guess.
+        if (m.fundingHours === null)
+            continue;
+        // Skip markets whose size precision the venue does not publish — a leg could
+        // not be sized to the venue's lot, and substituting a static guess mis-sizes it.
+        if (m.sizeDecimals === null)
+            continue;
+        result.push({
             symbol: m.symbol,
             rate: parseFloat(m.fundingRate),
             price: parseFloat(m.markPrice),
             sizeDecimals: m.sizeDecimals,
             maxLeverage: m.maxLeverage,
             fundingHours: m.fundingHours,
-        }));
+        });
     }
-    catch {
-        return [];
+    return result;
+}
+/**
+ * Cancel the open orders of `symbols` (the bot's own) on every venue in `adapters` — never an
+ * account-wide cancel. Each failure is logged (never "cancelled"); nothing is logged as
+ * cancelled when the bot traded no symbol.
+ */
+export async function cancelBotSymbols(adapters, symbols, tag, log) {
+    if (symbols.size === 0) {
+        log(`  ${tag} No bot symbols traded — no orders to cancel`);
+        return;
+    }
+    for (const [name, a] of adapters) {
+        for (const sym of symbols) {
+            try {
+                await a.cancelAllOrders(sym);
+            }
+            catch (e) {
+                log(`  ${tag} WARNING: cancelling ${sym} orders on ${name} FAILED (${e instanceof Error ? e.message : String(e)}) — check: perp -e ${name} account orders`);
+            }
+        }
     }
+    log(`  ${tag} Cancel requested for ${[...symbols].join(", ")} on ${[...adapters.keys()].join(", ")}`);
 }

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

@@ -2,6 +2,8 @@ import type { Strategy, StrategyContext, StrategyAction, EnrichedSnapshot } from
 export declare class FundingArbV2Strategy implements Strategy {
     readonly name = "funding-arb-v2";
     private _config;
+    /** Symbols this bot entered or recovered this run — the only symbols its stop cancels orders on. */
+    private _traded;
     describe(): {
         description: string;
         params: ({
@@ -24,8 +26,38 @@ export declare class FundingArbV2Strategy implements Strategy {
     private get sizeUsd();
     private get scanIntervalSec();
     init(ctx: StrategyContext, _snapshot: EnrichedSnapshot): Promise<void>;
+    /**
+     * Pairs held on the venues: a long on one venue + a short of the same symbol and EXACTLY the
+     * same size on another. A single leg or a size-mismatched long/short is quarantined (both
+     * sizes recorded) — never tracked, never stacked on. A venue whose positions cannot be read
+     * throws (the start fails and is retried): unknown exposure is never "flat".
+     */
+    private recoverPositions;
     onTick(ctx: StrategyContext, _snapshot: EnrichedSnapshot): Promise<StrategyAction[]>;
+    /**
+     * Close every tracked position (reduce-only, verified). A position that cannot be
+     * closed is never dropped silently: it is quarantined (persisted with what is open)
+     * so no bot / arb path touches it until a human resolves it.
+     */
     onStop(ctx: StrategyContext): Promise<StrategyAction[]>;
+    /** A live position of `symbol` on one of the venues that the bot does not track (or an unreadable venue): no entry on top of it. */
+    private heldUntracked;
+    private quarantine;
+    /**
+     * Long then short, each verified; the short is sized to the long's verified fill and
+     * any excess the short did not cover is trimmed off the long (reduce-only, verified).
+     * A definite short failure rolls the long back reduce-only. Returns the hedged size
+     * (both legs), or null when nothing is open / the symbol was quarantined.
+     */
+    private openPosition;
+    /**
+     * Close both legs reduce-only with the opened size, verified. Reduce-only makes a
+     * retry safe (a leg already flat is rejected, never re-opened), so a definite failure
+     * of the LONG close keeps the (still hedged) position for the next tick; MAX_CLOSE_FAILURES
+     * in a row, an unknown outcome, or a short close that definitely failed once the long is
+     * closed (naked short) quarantines it. Returns true when both legs are flat.
+     */
+    private closePosition;
     private getAdapters;
     /** Convert 8h funding rate difference to annualized spread % */
     private annualizeSpread;