perp-cli 0.12.17 → 0.14.0

package/dist/strategies/funding-arb.js

@@ -1,10 +1,20 @@
+import { assertCanClosePositions } from "../exchanges/trading-v2.js";
+import { MAX_PRICE_DEVIATION_PCT } from "../exchanges/index.js";
 import { symbolMatch, logSettledRejections } from "../utils.js";
+import { logExecution } from "../execution-log.js";
 import { updateJobState } from "../jobs.js";
-import { fetchAllBalances, computeRebalancePlan, hasEnoughBalance } from "../rebalance.js";
+import { invalidateCache } from "../cache.js";
+import { fetchAllBalances, computeRebalancePlan, hasEnoughBalance, marketLeverageOf, requiredArbMargin } from "../rebalance.js";
 import { checkArbLiquidity } from "../liquidity.js";
 import { computeAnnualSpread } from "../funding.js";
 import { fetchPacificaPrices, fetchHyperliquidMeta, fetchLighterOrderBookDetails, fetchLighterFundingRates, } from "../shared-api.js";
-import { computeMatchedSize, reconcileArbFills } from "../arb-sizing.js";
+import { computeMatchedSize } from "../arb-sizing.js";
+import { closePerpPairVerified, openPerpPairVerified } from "../commands/arb-auto.js";
+import { closePerpVerified, isOutcomeUnknown } from "../bot/perp-order.js";
+import { isQuarantined, quarantineSymbol } from "../bot/quarantine.js";
+import { isPositionGone, matchSymbol } from "../bot/strategies/funding-arb-utils.js";
+/** Quarantine source for `perp strategy funding-arb` (src/bot/quarantine.ts). */
+const SOURCE = "funding-arb-cli";
 async function fetchAllRates() {
     // SSOT rule #2: each DEX is independent. allSettled keeps the comparison
     // alive when one DEX errors out, while rejection reasons get logged to
@@ -56,7 +66,19 @@ async function fetchAllRates() {
     ];
 }
 // annualize: use computeAnnualSpread from funding.ts for cross-exchange comparison
+/**
+ * `perp strategy funding-arb` loop. With autoExecute (design §12.3):
+ *  - entry = openPerpPairVerified (long, then the short sized to the long's VERIFIED fill;
+ *    definite short failure → reduce-only rollback; unknown outcome → quarantine). A lot-size
+ *    rejection is never resubmitted blindly: the long is re-sized only when it was definitely
+ *    not placed; a rejected short is placed once at the lot-floored verified long fill;
+ *  - close / max-drawdown close = closePerpPairVerified with the venue position size strings
+ *    (reduce-only, verified, one residual close, quarantine on unknown / unhedged);
+ *  - quarantined symbols (src/bot/quarantine.ts) are never entered or closed.
+ */
 export async function runFundingArb(adapters, params, jobId, log = console.log) {
+    for (const a of adapters.values())
+        assertCanClosePositions(a, `Funding arb on ${a.name}`);
     const maxPos = params.maxPositions ?? 3;
     const closeSpread = params.closeSpread ?? 5;
     const positions = [];
@@ -105,28 +127,19 @@ export async function runFundingArb(adapters, params, jobId, log = console.log)
                     if (currentSpread <= closeSpread) {
                         log(`[ARB] CLOSE signal: ${pos.symbol} spread ${currentSpread.toFixed(1)}% <= ${closeSpread}%`);
                         if (params.autoExecute) {
-                            const longAdapter = adapters.get(pos.longExchange);
-                            const shortAdapter = adapters.get(pos.shortExchange);
-                            if (longAdapter && shortAdapter) {
-                                try {
-                                    await Promise.all([
-                                        longAdapter.marketOrder(pos.symbol, "sell", pos.size),
-                                        shortAdapter.marketOrder(pos.symbol, "buy", pos.size),
-                                    ]);
-                                    log(`[ARB] CLOSED ${pos.symbol} — both legs unwound`);
-                                    // Estimate P&L from funding collected
-                                    const hoursOpen = (Date.now() - pos.openedAt) / (1000 * 60 * 60);
-                                    // entrySpread is annualized %; convert to per-hour rate
-                                    const hourlySpreadRate = pos.entrySpread / 100 / (24 * 365);
-                                    const estimatedFunding = hourlySpreadRate * hoursOpen * Number(pos.size) * pos.entryPrices.long;
-                                    log(`[ARB] Est. funding P&L: ~$${estimatedFunding.toFixed(2)} (${hoursOpen.toFixed(1)}h open)`);
-                                }
-                                catch (err) {
-                                    const msg = err instanceof Error ? err.message : String(err);
-                                    log(`[ARB] Close error: ${msg}`);
-                                    continue; // don't remove position if close failed
-                                }
+                            if (isQuarantined(pos.symbol, log)) {
+                                log(`[ARB] ${pos.symbol} is quarantined — not closing (perp strategy quarantine)`);
+                                continue;
                             }
+                            const closed = await closeArbPosition(pos, adapters, log);
+                            if (!closed)
+                                continue; // still open (failed) or quarantined — keep tracking
+                            // Estimate P&L from funding collected
+                            const hoursOpen = (Date.now() - pos.openedAt) / (1000 * 60 * 60);
+                            // entrySpread is annualized %; convert to per-hour rate
+                            const hourlySpreadRate = pos.entrySpread / 100 / (24 * 365);
+                            const estimatedFunding = hourlySpreadRate * hoursOpen * Number(pos.size) * pos.entryPrices.long;
+                            log(`[ARB] Est. funding P&L: ~$${estimatedFunding.toFixed(2)} (${hoursOpen.toFixed(1)}h open)`);
                         }
                         positions.splice(i, 1);
                     }
@@ -139,11 +152,14 @@ export async function runFundingArb(adapters, params, jobId, log = console.log)
                         if (totalPnl < -params.maxDrawdown) {
                             log(`[ARB] MAX DRAWDOWN hit: uPnL $${totalPnl.toFixed(2)} < -$${params.maxDrawdown}`);
                             log(`[ARB] Closing all ${positions.length} positions...`);
-                            await closeAllPositions(positions, adapters, log);
+                            const stillOpen = await closeAllPositions(positions, adapters, log);
                             positions.length = 0;
+                            positions.push(...stillOpen);
                         }
                     }
-                    catch { /* non-critical */ }
+                    catch (err) {
+                        log(`[ARB] Drawdown check failed: ${err instanceof Error ? err.message : String(err)}`);
+                    }
                 }
                 // ── Phase 3: Balance check + rebalance trigger ──
                 let balanceSnapshots = null;
@@ -178,6 +194,8 @@ export async function runFundingArb(adapters, params, jobId, log = console.log)
                             continue;
                         if (positions.length >= maxPos)
                             break;
+                        if (params.autoExecute && isQuarantined(symbol, log))
+                            continue;
                         // Only consider exchanges we have adapters for
                         const available = symbolRates.filter((r) => adapters.has(r.exchange));
                         if (available.length < 2)
@@ -187,6 +205,13 @@ export async function runFundingArb(adapters, params, jobId, log = console.log)
                         const highest = available[available.length - 1];
                         if (lowest.exchange === highest.exchange)
                             continue;
+                        // Same ticker on two venues is not proof of the same asset: the chosen pair must agree on price.
+                        const pairGapPct = Math.abs(lowest.markPrice - highest.markPrice) / ((lowest.markPrice + highest.markPrice) / 2) * 100;
+                        if (!(pairGapPct <= MAX_PRICE_DEVIATION_PCT)) {
+                            if (cycleCount === 1)
+                                log(`[ARB] Skip ${symbol} ${lowest.exchange}↔${highest.exchange}: mark gap ${pairGapPct.toFixed(1)}% > ${MAX_PRICE_DEVIATION_PCT}% (likely a different asset)`);
+                            continue;
+                        }
                         const annualSpread = computeAnnualSpread(highest.fundingRate, highest.exchange, lowest.fundingRate, lowest.exchange);
                         if (annualSpread >= params.minSpread) {
                             const longEx = lowest.exchange;
@@ -212,64 +237,69 @@ export async function runFundingArb(adapters, params, jobId, log = console.log)
                                 }
                                 // Check balances before trading
                                 if (balanceSnapshots) {
-                                    if (!hasEnoughBalance(balanceSnapshots, longEx, matched.notional) ||
-                                        !hasEnoughBalance(balanceSnapshots, shortEx, matched.notional)) {
-                                        log(`[ARB] Skip ${symbol}: insufficient balance on ${longEx} or ${shortEx} (need ~$${matched.notional.toFixed(0)} per leg)`);
-                                        continue;
-                                    }
-                                }
-                                try {
-                                    log(`[ARB] Opening: ${matched.size} ${symbol} on both legs ($${matched.notional.toFixed(0)}/leg, slippage ~${liq.longSlippage.toFixed(2)}%/${liq.shortSlippage.toFixed(2)}%)...`);
+                                    // Margin at the leverage each venue applies to the market (unknown → 1x, see requiredArbMargin).
+                                    let longLev;
+                                    let shortLev;
                                     try {
-                                        await Promise.all([
-                                            longAdapter.marketOrder(symbol, "buy", matched.size),
-                                            shortAdapter.marketOrder(symbol, "sell", matched.size),
-                                        ]);
+                                        [longLev, shortLev] = await Promise.all([marketLeverageOf(longAdapter, symbol), marketLeverageOf(shortAdapter, symbol)]);
                                     }
-                                    catch (orderErr) {
-                                        const errMsg = orderErr instanceof Error ? orderErr.message : String(orderErr);
-                                        const lotMatch = errMsg.match(/not a multiple of lot size (\d+(?:\.\d+)?)/);
-                                        if (lotMatch) {
-                                            const lotSize = parseFloat(lotMatch[1]);
-                                            log(`[ARB] Lot size ${lotSize} detected, recalculating...`);
-                                            matched = computeMatchedSize(liq.adjustedSizeUsd, highest.markPrice, longEx, shortEx, { lotSize });
-                                            if (!matched) {
-                                                log(`[ARB] Skip ${symbol}: can't meet lot size ${lotSize}`);
-                                                continue;
-                                            }
-                                            log(`[ARB] Retry: ${matched.size} ${symbol} ($${matched.notional.toFixed(0)}/leg)`);
-                                            await Promise.all([
-                                                longAdapter.marketOrder(symbol, "buy", matched.size),
-                                                shortAdapter.marketOrder(symbol, "sell", matched.size),
-                                            ]);
-                                        }
-                                        else {
-                                            throw orderErr;
-                                        }
+                                    catch (e) {
+                                        log(`[ARB] Skip ${symbol}: could not read the market leverage (${e instanceof Error ? e.message : String(e)})`);
+                                        continue;
                                     }
-                                    // Verify fills match, correct if needed
-                                    try {
-                                        const recon = await reconcileArbFills(longAdapter, shortAdapter, symbol, log);
-                                        if (!recon.matched) {
-                                            log(`[ARB] WARNING: fills not matched after correction attempt`);
-                                        }
+                                    if (!hasEnoughBalance(balanceSnapshots, longEx, matched.notional, longLev) ||
+                                        !hasEnoughBalance(balanceSnapshots, shortEx, matched.notional, shortLev)) {
+                                        const need = (ex, lev) => `${ex} ~$${requiredArbMargin(matched.notional, lev).toFixed(2)} (${lev !== null ? `${lev}x` : "leverage unknown → 1x"})`;
+                                        log(`[ARB] Skip ${symbol}: insufficient available balance for $${matched.notional.toFixed(2)}/leg — need ${need(longEx, longLev)}, ${need(shortEx, shortLev)}`);
+                                        continue;
                                     }
-                                    catch { /* non-critical */ }
-                                    positions.push({
-                                        symbol,
-                                        longExchange: longEx,
-                                        shortExchange: shortEx,
-                                        size: matched.size,
-                                        entrySpread: annualSpread,
-                                        openedAt: Date.now(),
-                                        entryPrices: { long: lowest.markPrice, short: highest.markPrice },
-                                    });
-                                    log(`[ARB] OPENED ${symbol} delta-neutral (${positions.length}/${maxPos})`);
                                 }
-                                catch (err) {
-                                    const msg = err instanceof Error ? err.message : String(err);
-                                    log(`[ARB] Entry error: ${msg}`);
+                                log(`[ARB] Opening: ${matched.size} ${symbol} — long ${longEx} then short ${shortEx}, each verified ($${matched.notional.toFixed(0)}/leg, slippage ~${liq.longSlippage.toFixed(2)}%/${liq.shortSlippage.toFixed(2)}%)...`);
+                                const openPair = (size) => openPerpPairVerified({
+                                    source: SOURCE, sym: symbol,
+                                    longAdapter, longExch: longEx, longSym: symbol,
+                                    shortAdapter, shortExch: shortEx, shortSym: symbol,
+                                    size, smart: false, log, shortLotRetry: true,
+                                });
+                                let res = await openPair(matched.size);
+                                if (res.status === "not_opened" && res.rolledBack === null && res.lotSize !== null) {
+                                    // The LONG was definitely rejected for lot size (nothing placed): recompute once.
+                                    const lotSize = res.lotSize;
+                                    log(`[ARB] Lot size ${lotSize} on ${longEx} — recalculating (nothing was placed)`);
+                                    matched = computeMatchedSize(liq.adjustedSizeUsd, highest.markPrice, longEx, shortEx, { lotSize });
+                                    if (!matched) {
+                                        log(`[ARB] Skip ${symbol}: can't meet lot size ${lotSize}`);
+                                        continue;
+                                    }
+                                    log(`[ARB] Retry: ${matched.size} ${symbol} ($${matched.notional.toFixed(0)}/leg)`);
+                                    res = await openPair(matched.size);
+                                }
+                                if (res.status === "quarantined") {
+                                    log(`[ARB] Entry ${symbol} QUARANTINED: ${res.reason} — exposure: ${res.exposure}`);
+                                    continue;
+                                }
+                                if (res.status === "not_opened") {
+                                    log(`[ARB] Entry error ${symbol}: ${res.reason}${res.rolledBack !== null ? ` (long ${res.rolledBack} rolled back)` : ""}`);
+                                    continue;
                                 }
+                                if (res.trimmed !== "0")
+                                    log(`[ARB] Short filled ${res.hedged} — trimmed the long by ${res.trimmed} (reduce-only)`);
+                                positions.push({
+                                    symbol,
+                                    longExchange: longEx,
+                                    shortExchange: shortEx,
+                                    size: res.hedged,
+                                    entrySpread: annualSpread,
+                                    openedAt: Date.now(),
+                                    entryPrices: { long: lowest.markPrice, short: highest.markPrice },
+                                });
+                                // Entry record: `arb status` / `arb close` confirm this pair from it (arbPairProvenance).
+                                logExecution({
+                                    type: "arb_entry", exchange: `${longEx}+${shortEx}`, symbol, side: "entry", size: res.hedged,
+                                    status: "success", dryRun: false,
+                                    meta: { arbPairId: `${symbol.toUpperCase()}:${longEx}:${shortEx}`, longExchange: longEx, shortExchange: shortEx, spread: annualSpread, source: SOURCE },
+                                });
+                                log(`[ARB] OPENED ${symbol} delta-neutral ${res.hedged}/leg (${positions.length}/${maxPos})`);
                             }
                         }
                     }
@@ -314,23 +344,106 @@ export async function runFundingArb(adapters, params, jobId, log = console.log)
     }
     log(`[ARB] Funding rate arbitrage stopped. Positions: ${positions.length}`);
 }
+/** Venue position size string for one leg (abs, as the venue reports it), or null when flat. Read errors propagate. */
+async function venueLegSize(adapter, symbol, side) {
+    invalidateCache("acct"); // the reduce-only close is sized from this read: never a cached position
+    const p = (await adapter.getPositions()).find(x => matchSymbol(x.symbol, symbol) && x.side === side);
+    if (p === undefined)
+        return null;
+    const abs = p.size.replace(/^-/, "");
+    return Number(abs) > 0 ? abs : null;
+}
+/**
+ * Close one tracked pair: reduce-only, verified, legs sequential (closePerpPairVerified), each
+ * sized from the venue's own position size string, capped at the tracked size (never rounded
+ * up, never another position's size). A leg already gone → the other leg alone (reduce-only,
+ * verified, one residual close). Unknown outcome / unhedged residual → quarantined. Returns
+ * true only when this pair is flat.
+ */
+async function closeArbPosition(pos, adapters, log) {
+    const longAdapter = adapters.get(pos.longExchange);
+    const shortAdapter = adapters.get(pos.shortExchange);
+    if (!longAdapter || !shortAdapter) {
+        log(`[ARB] Close ${pos.symbol}: adapter missing (${pos.longExchange}/${pos.shortExchange}) — left open`);
+        return false;
+    }
+    const cap = (venue) => (venue === null ? null : Number(venue) > Number(pos.size) ? pos.size : venue);
+    let longSize;
+    let shortSize;
+    try {
+        [longSize, shortSize] = await Promise.all([
+            venueLegSize(longAdapter, pos.symbol, "long").then(cap),
+            venueLegSize(shortAdapter, pos.symbol, "short").then(cap),
+        ]);
+    }
+    catch (err) {
+        log(`[ARB] Close ${pos.symbol}: position read failed (${err instanceof Error ? err.message : String(err)}) — nothing sent, retry next cycle`);
+        return false;
+    }
+    if (longSize === null && shortSize === null) {
+        log(`[ARB] ${pos.symbol}: both legs already flat — removing from tracking`);
+        return true;
+    }
+    if (longSize !== null && shortSize !== null) {
+        const res = await closePerpPairVerified({
+            source: SOURCE, sym: pos.symbol,
+            longAdapter, longExch: pos.longExchange, longSym: pos.symbol, longSize,
+            shortAdapter, shortExch: pos.shortExchange, shortSym: pos.symbol, shortSize,
+            smart: false, log,
+        });
+        if (res.status === "closed") {
+            logExecution({
+                type: "arb_close", exchange: `${pos.longExchange}+${pos.shortExchange}`, symbol: pos.symbol, side: "close", size: pos.size,
+                status: "success", dryRun: false,
+                meta: { arbPairId: `${pos.symbol.toUpperCase()}:${pos.longExchange}:${pos.shortExchange}`, longExchange: pos.longExchange, shortExchange: pos.shortExchange, source: SOURCE },
+            });
+            log(`[ARB] CLOSED ${pos.symbol} — both legs unwound (long ${longSize}, short ${shortSize})`);
+            return true;
+        }
+        if (res.status === "failed") {
+            log(`[ARB] Close error ${pos.symbol}: ${res.reason} — hedge intact`);
+            return false;
+        }
+        log(`[ARB] Close ${pos.symbol} QUARANTINED: ${res.reason}`);
+        return false;
+    }
+    // One leg is gone (liquidated / closed elsewhere): close the orphan leg alone.
+    const [adapter, venue, side, size, leg] = longSize !== null
+        ? [longAdapter, pos.longExchange, "sell", longSize, "long"]
+        : [shortAdapter, pos.shortExchange, "buy", shortSize, "short"];
+    log(`[ARB] ${pos.symbol}: the other leg is gone — closing the orphaned ${leg} ${size} on ${venue} (reduce-only)`);
+    const q = (reason) => {
+        quarantineSymbol(SOURCE, pos.symbol, reason, `Check ${pos.symbol} on ${pos.longExchange} and ${pos.shortExchange}; close by hand, then: perp strategy quarantine-clear ${pos.symbol}`, log);
+        return false;
+    };
+    try {
+        const c = await closePerpVerified(adapter, venue, pos.symbol, side, size);
+        if (c.residual > 0)
+            return q(`orphaned ${leg} close on ${venue} closed ${c.closed} of ${size}, ${c.residual} still open${c.note !== null ? ` (${c.note})` : ""}`);
+    }
+    catch (err) {
+        if (!isOutcomeUnknown(err) && isPositionGone(err))
+            return true;
+        return q(`orphaned ${leg} ${size} on ${venue}: close ${isOutcomeUnknown(err) ? "outcome unknown" : "failed"} (${err instanceof Error ? err.message : String(err)}) — unhedged`);
+    }
+    log(`[ARB] Closed orphaned ${leg} ${size} ${pos.symbol} on ${venue}`);
+    return true;
+}
+/** Emergency close of every tracked pair (verified, reduce-only). Returns the pairs still open. */
 async function closeAllPositions(positions, adapters, log) {
+    const stillOpen = [];
     for (const pos of positions) {
-        const longAdapter = adapters.get(pos.longExchange);
-        const shortAdapter = adapters.get(pos.shortExchange);
-        if (!longAdapter || !shortAdapter)
+        if (isQuarantined(pos.symbol, log)) {
+            log(`[ARB] ${pos.symbol} is quarantined — left open (perp strategy quarantine)`);
+            stillOpen.push(pos);
             continue;
-        try {
-            await Promise.all([
-                longAdapter.marketOrder(pos.symbol, "sell", pos.size),
-                shortAdapter.marketOrder(pos.symbol, "buy", pos.size),
-            ]);
-            log(`[ARB] Emergency closed ${pos.symbol}`);
-        }
-        catch (err) {
-            log(`[ARB] Failed to close ${pos.symbol}: ${err instanceof Error ? err.message : err}`);
         }
+        if (await closeArbPosition(pos, adapters, log))
+            log(`[ARB] Emergency closed ${pos.symbol}`);
+        else
+            stillOpen.push(pos);
     }
+    return stillOpen;
 }
 function sleep(ms) {
     return new Promise((r) => setTimeout(r, ms));

package/dist/strategies/grid.d.ts

@@ -10,11 +10,32 @@ export interface GridParams {
     intervalSec?: number;
     maxRuntime?: number;
     trailingStop?: number;
+    /**
+     * At stop (max runtime, trailing stop, SIGINT): close the grid's own inventory — the position
+     * change since the grid started — reduce-only, verified (closePerpVerified). Default false: the
+     * inventory is left open and reported (warning + result.inventory).
+     */
+    closeOnStop?: boolean;
+}
+/** The grid's position change on `symbol` between start and stop (signed base: + long, − short). */
+export interface GridInventory {
+    /** Signed position when the grid started. */
+    startSize: string;
+    /** Signed position after the remaining grid orders were cancelled; null = could not be read. */
+    endSize: string | null;
+    /** endSize − startSize (the grid's own net fills); null when endSize is unknown. */
+    gridDelta: string | null;
+    /** Base closed by --close-on-stop (0 when not requested / nothing to close). */
+    closed: string;
+    /** Inventory still open after stop (|gridDelta| − closed); null when unknown. */
+    leftOpen: string | null;
+    note: string | null;
 }
 export interface GridState {
     gridLines: GridLine[];
     activeOrders: Map<string, string>;
     fills: number;
+    /** Estimated PnL of COMPLETED round trips only (grid step × size per take-profit fill). */
     totalPnl: number;
     peakEquity: number;
     startedAt: number;
@@ -25,10 +46,20 @@ interface GridLine {
     side: "buy" | "sell";
     size: number;
     filled: boolean;
+    /** The line's resting order is the take-profit leg of an earlier fill (its fill completes a round trip). */
+    flipped: boolean;
 }
 export declare function runGrid(adapter: ExchangeAdapter, params: GridParams, jobId?: string, log?: (msg: string) => void): Promise<{
     fills: number;
     totalPnl: number;
     runtime: number;
+    inventory: GridInventory;
 }>;
+/**
+ * The grid's inventory at stop: position now − position at start. Without closeOnStop it is
+ * left open and reported (WARNING). With closeOnStop the part still held in the same direction is
+ * closed reduce-only (closePerpVerified); a delta the current position no longer holds (the
+ * position was reduced / flipped by something else) is not closed — closing it would open a position.
+ */
+export declare function settleGridInventory(adapter: ExchangeAdapter, symbol: string, startSize: string, closeOnStop: boolean, log: (msg: string) => void): Promise<GridInventory>;
 export {};

package/dist/strategies/grid.js

@@ -1,5 +1,20 @@
+import { assertCanClosePositions } from "../exchanges/trading-v2.js";
 import { updateJobState } from "../jobs.js";
+import { closePerpVerified } from "../bot/perp-order.js";
+import { formatComputedPrice } from "../exchanges/precision.js";
+import { alignComputedLimitPrice } from "../bot/quote-rules.js";
+import { symbolMatch } from "../utils.js";
+import { venueRateString } from "../utils/numeric.js";
+/** Signed position of `symbol` (+ long, − short, 0 none) as a decimal string. */
+async function signedPosition(adapter, symbol) {
+    const p = (await adapter.getPositions()).find(x => symbolMatch(x.symbol, symbol));
+    if (p === undefined)
+        return "0";
+    const abs = p.size.replace(/^-/, "");
+    return p.side === "short" ? `-${abs}` : abs;
+}
 export async function runGrid(adapter, params, jobId, log = console.log) {
+    assertCanClosePositions(adapter, `Grid on ${adapter.name}`);
     const { symbol, upperPrice, lowerPrice, grids, totalSize } = params;
     const intervalMs = (params.intervalSec ?? 10) * 1000;
     const maxRuntime = (params.maxRuntime ?? 0) * 1000;
@@ -27,6 +42,7 @@ export async function runGrid(adapter, params, jobId, log = console.log) {
             side: "buy", // will be set based on current price
             size: sizePerGrid,
             filled: false,
+            flipped: false,
         });
     }
     log(`[GRID] ${symbol} ${params.side} | ${grids} grids | $${lowerPrice} - $${upperPrice} | step $${step.toFixed(2)}`);
@@ -40,14 +56,17 @@ export async function runGrid(adapter, params, jobId, log = console.log) {
         startedAt: Date.now(),
         running: true,
     };
+    // Baseline position: the grid's inventory at stop is measured against it (a failed read stops here, nothing placed).
+    const startSize = await signedPosition(adapter, symbol);
     // Graceful shutdown
     const shutdown = () => { state.running = false; };
     process.on("SIGINT", shutdown);
     process.on("SIGTERM", shutdown);
+    let roundTrips = 0;
     try {
         // Get current price to determine buy/sell sides
         const markets = await adapter.getMarkets();
-        const market = markets.find(m => m.symbol.toUpperCase() === symbol.toUpperCase());
+        const market = markets.find(m => symbolMatch(m.symbol, symbol));
         const currentPrice = market ? parseFloat(market.markPrice) : (upperPrice + lowerPrice) / 2;
         // Assign sides: buy below current, sell above current
         for (const line of gridLines) {
@@ -84,6 +103,8 @@ export async function runGrid(adapter, params, jobId, log = console.log) {
                         const line = gridLines[i];
                         state.fills++;
                         newFills++;
+                        if (line.flipped)
+                            roundTrips++;
                         line.filled = true;
                         // Flip side: buy → sell, sell → buy (take profit at next grid)
                         const newSide = line.side === "buy" ? "sell" : "buy";
@@ -92,12 +113,13 @@ export async function runGrid(adapter, params, jobId, log = console.log) {
                             : line.price - step; // buy one grid below
                         if (newPrice >= lowerPrice && newPrice <= upperPrice) {
                             try {
-                                const result = await adapter.limitOrder(symbol, newSide, String(newPrice.toFixed(2)), String(line.size));
+                                const result = await adapter.limitOrder(symbol, newSide, await alignComputedLimitPrice(adapter, symbol, newSide, formatComputedPrice(newPrice)), String(line.size));
                                 const newOrderId = String(result?.orderId ?? result?.oid ?? result?.id ?? "");
                                 state.activeOrders.set(String(i), newOrderId);
                                 line.side = newSide;
                                 line.price = newPrice;
                                 line.filled = false;
+                                line.flipped = !line.flipped;
                             }
                             catch (err) {
                                 const msg = err instanceof Error ? err.message : String(err);
@@ -110,9 +132,9 @@ export async function runGrid(adapter, params, jobId, log = console.log) {
                     }
                 }
                 if (newFills > 0) {
-                    // Estimate PnL from grid spacing
-                    state.totalPnl += newFills * step * sizePerGrid;
-                    log(`[GRID] ${newFills} fill(s) | Total fills: ${state.fills} | Est. PnL: $${state.totalPnl.toFixed(2)}`);
+                    // Estimate PnL from grid spacing — completed round trips only (an opening fill earns nothing yet).
+                    state.totalPnl = roundTrips > 0 ? Number(formatComputedPrice(roundTrips * step * sizePerGrid)) : 0;
+                    log(`[GRID] ${newFills} fill(s) | Total fills: ${state.fills} | Round trips: ${roundTrips} | Est. PnL: $${state.totalPnl}`);
                 }
                 // Update job state
                 if (jobId) {
@@ -152,23 +174,79 @@ export async function runGrid(adapter, params, jobId, log = console.log) {
         try {
             await adapter.cancelAllOrders(symbol);
         }
-        catch {
-            // best-effort
+        catch (e) {
+            log(`[GRID] WARNING: cancelling the remaining ${symbol} orders failed (${e instanceof Error ? e.message : String(e)}) — check: perp account orders -e ${adapter.name}`);
         }
     }
+    const inventory = await settleGridInventory(adapter, symbol, startSize, params.closeOnStop === true, log);
     const runtime = Math.floor((Date.now() - state.startedAt) / 1000);
-    log(`[GRID] Done. ${state.fills} fills, est. PnL $${state.totalPnl.toFixed(2)}, runtime ${runtime}s`);
+    log(`[GRID] Done. ${state.fills} fills (${roundTrips} round trips), est. PnL $${state.totalPnl}, runtime ${runtime}s`);
     if (jobId) {
-        updateJobState(jobId, { status: "done", result: { fills: state.fills, totalPnl: state.totalPnl, runtime } });
+        updateJobState(jobId, { status: "done", result: { fills: state.fills, totalPnl: state.totalPnl, runtime, inventory } });
+    }
+    return { fills: state.fills, totalPnl: state.totalPnl, runtime, inventory };
+}
+/**
+ * The grid's inventory at stop: position now − position at start. Without closeOnStop it is
+ * left open and reported (WARNING). With closeOnStop the part still held in the same direction is
+ * closed reduce-only (closePerpVerified); a delta the current position no longer holds (the
+ * position was reduced / flipped by something else) is not closed — closing it would open a position.
+ */
+export async function settleGridInventory(adapter, symbol, startSize, closeOnStop, log) {
+    let endSize;
+    try {
+        endSize = await signedPosition(adapter, symbol);
+    }
+    catch (e) {
+        const note = `position could not be read after stop (${e instanceof Error ? e.message : String(e)})`;
+        log(`[GRID] WARNING: ${note} — the grid may have left a ${symbol} position open. Check: perp account positions -e ${adapter.name}`);
+        return { startSize, endSize: null, gridDelta: null, closed: "0", leftOpen: null, note };
+    }
+    const dec = Math.max((startSize.split(".")[1] ?? "").length, (endSize.split(".")[1] ?? "").length);
+    const delta = Number(venueRateString(Number(endSize) - Number(startSize), "grid inventory"));
+    const gridDelta = delta.toFixed(dec);
+    const base = { startSize, endSize, gridDelta };
+    if (delta === 0)
+        return { ...base, closed: "0", leftOpen: "0", note: null };
+    const deltaAbs = Math.abs(delta).toFixed(dec);
+    const dir = delta > 0 ? "long" : "short";
+    if (!closeOnStop) {
+        log(`[GRID] WARNING: the grid left ${deltaAbs} ${symbol} ${dir} open (position ${startSize} → ${endSize}). Close it: perp trade close ${symbol} -e ${adapter.name} (or rerun with --close-on-stop)`);
+        return { ...base, closed: "0", leftOpen: deltaAbs, note: "left open (no --close-on-stop)" };
+    }
+    const end = Number(endSize);
+    const held = Math.sign(end) === Math.sign(delta) ? Math.min(Math.abs(delta), Math.abs(end)) : 0;
+    if (held === 0) {
+        const note = `the position (${endSize}) no longer holds the grid's ${dir} inventory — not closed (it would open a position)`;
+        log(`[GRID] WARNING: ${note}. Check: perp account positions -e ${adapter.name}`);
+        return { ...base, closed: "0", leftOpen: deltaAbs, note };
+    }
+    const size = held.toFixed(dec);
+    log(`[GRID] --close-on-stop: closing ${size} ${symbol} ${dir} (reduce-only, verified)...`);
+    try {
+        const c = await closePerpVerified(adapter, adapter.name, symbol, delta > 0 ? "sell" : "buy", size, { decimals: dec });
+        const closed = c.closed.toFixed(dec);
+        const leftOpen = Math.max(0, Math.abs(delta) - c.closed).toFixed(dec);
+        if (c.residual > 0 || Number(leftOpen) > 0) {
+            log(`[GRID] WARNING: closed ${closed}; ${leftOpen} ${symbol} still open${c.note !== null ? ` (${c.note})` : ""}. Check: perp account positions -e ${adapter.name}`);
+        }
+        else {
+            log(`[GRID] Closed the grid inventory (${closed} ${symbol}).`);
+        }
+        return { ...base, closed, leftOpen, note: c.note };
+    }
+    catch (e) {
+        const note = `close failed: ${e instanceof Error ? e.message : String(e)}`;
+        log(`[GRID] WARNING: ${note} — ${deltaAbs} ${symbol} ${dir} may still be open. Check: perp account positions -e ${adapter.name}`);
+        return { ...base, closed: "0", leftOpen: null, note };
     }
-    return { fills: state.fills, totalPnl: state.totalPnl, runtime };
 }
 async function placeGridOrders(adapter, symbol, gridLines, state, log) {
     let placed = 0;
     for (let i = 0; i < gridLines.length; i++) {
         const line = gridLines[i];
         try {
-            const result = await adapter.limitOrder(symbol, line.side, String(line.price.toFixed(2)), String(line.size));
+            const result = await adapter.limitOrder(symbol, line.side, await alignComputedLimitPrice(adapter, symbol, line.side, formatComputedPrice(line.price)), String(line.size));
             const orderId = String(result?.orderId ?? result?.oid ?? result?.id ?? "");
             state.activeOrders.set(String(i), orderId);
             placed++;

package/dist/strategies/pending-stop.d.ts

@@ -0,0 +1,8 @@
+import type { ExchangeAdapter } from "../exchanges/index.js";
+import { PerpError } from "../errors.js";
+/**
+ * An order of a DCA / TWAP run whose outcome or fill size is unknown: it is NEVER resubmitted.
+ * The symbol is quarantined (every automated path skips it until a human clears it) and the
+ * returned ORDER_PENDING error ends the run.
+ */
+export declare function pendingStop(source: "dca" | "twap", adapter: ExchangeAdapter, symbol: string, reason: string, log: (msg: string) => void): PerpError;

package/dist/strategies/pending-stop.js

@@ -0,0 +1,12 @@
+import { PerpError } from "../errors.js";
+import { quarantineSymbol } from "../bot/quarantine.js";
+/**
+ * An order of a DCA / TWAP run whose outcome or fill size is unknown: it is NEVER resubmitted.
+ * The symbol is quarantined (every automated path skips it until a human clears it) and the
+ * returned ORDER_PENDING error ends the run.
+ */
+export function pendingStop(source, adapter, symbol, reason, log) {
+    const remediation = `Check ${symbol} on ${adapter.name} (perp -e ${adapter.name} account positions; perp -e ${adapter.name} account orders) — do NOT resubmit; fix by hand, then: perp strategy quarantine-clear ${symbol}`;
+    quarantineSymbol(source, symbol, `${reason} — not resubmitted`, remediation, log);
+    return new PerpError("ORDER_PENDING", `${reason} — run stopped, ${symbol} quarantined`, { exchange: adapter.name, remediation });
+}