perp-cli 0.12.17 → 0.14.0

package/dist/plan-executor.js

@@ -1,6 +1,13 @@
+import { assertCanClosePositions } from "./exchanges/trading-v2.js";
 import { symbolMatch } from "./utils.js";
 import { logExecution } from "./execution-log.js";
 import { randomUUID } from "crypto";
+import { invalidateCache } from "./cache.js";
+import { PerpError, extractErrorMessage, isDefiniteOrderFailure, orderOutcomeUnknown } from "./errors.js";
+import { closePerpVerified, isOutcomeUnknown, placePerpVerified } from "./bot/perp-order.js";
+import { fillSizeString, sizeDecimalsOf } from "./exchanges/spot-result.js";
+import { quarantineSymbol } from "./bot/quarantine.js";
+import { resolveAdapterSlippage } from "./exchanges/slippage.js";
 /**
  * Validate a plan structure without executing it.
  */
@@ -67,6 +74,8 @@ export function validatePlan(plan) {
 /**
  * Execute a plan step by step.
  */
+/** Plan actions that place orders (open or close positions). */
+const PLAN_ORDER_ACTIONS = new Set(["market_order", "limit_order", "stop_order", "close_position"]);
 export async function executePlan(adapter, plan, opts) {
     const planId = randomUUID().slice(0, 8);
     const startTime = Date.now();
@@ -74,18 +83,40 @@ export async function executePlan(adapter, plan, opts) {
     const completedSteps = new Map();
     const dryRun = opts?.dryRun ?? false;
     const log = opts?.log ?? (() => { });
+    // A plan that places orders must be able to close them (rollback / close_position are
+    // reduce-only): refuse before the first step on a venue that cannot.
+    if (!dryRun && plan.steps.some(s => PLAN_ORDER_ACTIONS.has(s.action))) {
+        assertCanClosePositions(adapter, `Plan on ${adapter.name}`);
+    }
+    /** Order steps that completed, with their measured fill (market orders) for rollback. */
+    const placed = new Map();
+    const quarantined = new Set();
+    const finish = (status) => ({
+        planId,
+        status: quarantined.size > 0 && status !== "pending" ? "quarantined" : status,
+        steps: results,
+        quarantined: [...quarantined],
+        totalDurationMs: Date.now() - startTime,
+        timestamp: new Date().toISOString(),
+    });
+    const quarantine = (symbol, reason) => {
+        quarantineSymbol("plan-execute", symbol, `plan ${planId}: ${reason}`, `Check the ${symbol} position and open orders on ${adapter.name} (perp -e ${adapter.name} account positions / trade orders); fix by hand, then: perp strategy quarantine-clear ${symbol}`, log);
+        quarantined.add(symbol.toUpperCase());
+    };
     log(`[plan:${planId}] Starting ${plan.steps.length} steps (${dryRun ? "DRY RUN" : "LIVE"})`);
     for (const step of plan.steps) {
         const stepStart = Date.now();
         // Check dependency
         if (step.dependsOn) {
             const dep = completedSteps.get(step.dependsOn);
-            if (!dep || dep.status === "failed") {
+            // Only a dependency that actually succeeded (or was dry-run) lets the step run:
+            // failed / skipped / pending / rolled-back / missing all block it.
+            if (!dep || (dep.status !== "success" && dep.status !== "dry_run")) {
                 const result = {
                     stepId: step.id,
                     action: step.action,
                     status: "skipped",
-                    error: { code: "DEPENDENCY_FAILED", message: `Depends on ${step.dependsOn} which failed/missing` },
+                    error: { code: "DEPENDENCY_FAILED", message: `Depends on ${step.dependsOn} which is ${dep ? dep.status : "missing"}` },
                     durationMs: 0,
                 };
                 results.push(result);
@@ -107,7 +138,7 @@ export async function executePlan(adapter, plan, opts) {
             continue;
         }
         try {
-            const result = await executeStep(adapter, step, log);
+            const result = await executeStep(adapter, step, log, placed);
             const stepResult = {
                 stepId: step.id,
                 action: step.action,
@@ -120,8 +151,28 @@ export async function executePlan(adapter, plan, opts) {
             log(`[plan:${planId}] Step ${step.id} (${step.action}): success (${stepResult.durationMs}ms)`);
         }
         catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
+            const message = extractErrorMessage(err);
             const onFailure = step.onFailure ?? "abort";
+            if (ORDER_ACTIONS.has(step.action) && isOutcomeUnknown(err)) {
+                // The order may have been placed: never treat it as failed, never resubmit or roll it
+                // back. Stop the plan and quarantine the symbol (design §12.3).
+                const sym = String(step.params.symbol ?? "").toUpperCase();
+                log(`[plan:${planId}] Step ${step.id} (${step.action}): OUTCOME UNKNOWN — ${message}`);
+                quarantine(sym, `step ${step.id} (${step.action}) outcome unknown: ${message}`);
+                results.push({
+                    stepId: step.id,
+                    action: step.action,
+                    status: "pending",
+                    error: { code: "ORDER_PENDING", message },
+                    durationMs: Date.now() - stepStart,
+                });
+                if (onFailure === "rollback") {
+                    // Reverse completed steps on OTHER symbols only — the pending order's symbol is
+                    // quarantined and left untouched (a reversal there could not be measured).
+                    await rollbackSteps(adapter, results.filter(r => r.status === "success"), placed, sym, quarantine, log);
+                }
+                return finish("pending");
+            }
             log(`[plan:${planId}] Step ${step.id} (${step.action}): FAILED — ${message}`);
             if (onFailure === "skip") {
                 results.push({
@@ -136,7 +187,7 @@ export async function executePlan(adapter, plan, opts) {
             }
             if (onFailure === "rollback") {
                 log(`[plan:${planId}] Rolling back completed steps...`);
-                await rollbackSteps(adapter, results.filter(r => r.status === "success"), log);
+                await rollbackSteps(adapter, results.filter(r => r.status === "success"), placed, null, quarantine, log);
                 results.push({
                     stepId: step.id,
                     action: step.action,
@@ -144,13 +195,7 @@ export async function executePlan(adapter, plan, opts) {
                     error: { code: "STEP_FAILED", message },
                     durationMs: Date.now() - stepStart,
                 });
-                return {
-                    planId,
-                    status: "failed",
-                    steps: results,
-                    totalDurationMs: Date.now() - startTime,
-                    timestamp: new Date().toISOString(),
-                };
+                return finish("failed");
             }
             // abort
             results.push({
@@ -160,44 +205,80 @@ export async function executePlan(adapter, plan, opts) {
                 error: { code: "STEP_FAILED", message },
                 durationMs: Date.now() - stepStart,
             });
-            return {
-                planId,
-                status: results.some(r => r.status === "success") ? "partial" : "failed",
-                steps: results,
-                totalDurationMs: Date.now() - startTime,
-                timestamp: new Date().toISOString(),
-            };
+            return finish(results.some(r => r.status === "success") ? "partial" : "failed");
         }
     }
-    return {
-        planId,
-        status: dryRun ? "dry_run" : "completed",
-        steps: results,
-        totalDurationMs: Date.now() - startTime,
-        timestamp: new Date().toISOString(),
-    };
+    return finish(dryRun ? "dry_run" : "completed");
+}
+/** Steps that send an order (a thrown non-definite error = outcome unknown). */
+const ORDER_ACTIONS = new Set(["market_order", "limit_order", "stop_order", "close_position"]);
+/**
+ * Order id from a venue placement response: TradingV2 OrderResult.orderId, Aster/Binance
+ * `orderId`, Pacifica `order_id`, HL `response.data.statuses[0].resting.oid`, generic `id`.
+ * null when none is present (the rollback then refuses to guess).
+ */
+function extractOrderId(result) {
+    if (result === null || typeof result !== "object")
+        return null;
+    const r = result;
+    for (const k of ["orderId", "order_id", "oid", "id"]) {
+        const v = r[k];
+        if (typeof v === "string" && v.length > 0)
+            return v;
+        if (typeof v === "number" && Number.isFinite(v))
+            return String(v);
+    }
+    const data = (r.data ?? r.response?.data);
+    const statuses = data?.statuses;
+    for (const k of ["resting", "filled"]) { // HL: resting order, or a limit that filled immediately
+        const st = statuses?.[0]?.[k];
+        if (st && (typeof st.oid === "number" || typeof st.oid === "string"))
+            return String(st.oid);
+    }
+    if (data)
+        return extractOrderId(data);
+    return null;
+}
+/** Limit / stop placement: a typed definite failure stays; anything else may have placed the order → ORDER_PENDING. */
+async function sendRestingOrder(adapter, what, send) {
+    try {
+        return await send();
+    }
+    catch (e) {
+        throw isDefiniteOrderFailure(e) ? e : orderOutcomeUnknown(adapter.name, what, e);
+    }
 }
-async function executeStep(adapter, step, log) {
+async function executeStep(adapter, step, log, placed) {
     const p = step.params;
     const symbol = String(p.symbol ?? "").toUpperCase();
     const side = String(p.side ?? "");
     const size = String(p.size ?? "");
     switch (step.action) {
         case "market_order": {
-            const result = await adapter.marketOrder(symbol, side, size);
-            logExecution({ type: "market_order", exchange: adapter.name, symbol, side, size, status: "success", dryRun: false, meta: { planStep: step.id, clientId: step.clientId } });
-            return result;
+            // Fill MEASURED as the position delta (ORDER_PENDING when unconfirmed) — the rollback
+            // reverses exactly this size.
+            const fill = await placePerpVerified(adapter, adapter.name, symbol, side, size);
+            placed.set(step.id, { symbol, side, filledSize: fill.filledSize, decimals: sizeDecimalsOf(size), orderId: null });
+            logExecution({ type: "market_order", exchange: adapter.name, symbol, side, size, status: "success", dryRun: false, meta: { planStep: step.id, clientId: step.clientId, filledSize: fill.filledSize } });
+            return fill.raw;
         }
         case "limit_order": {
             const price = String(p.price ?? "");
-            const result = await adapter.limitOrder(symbol, side, price, size);
+            const result = await sendRestingOrder(adapter, `limit ${side} ${size} ${symbol} @ ${price}`, () => adapter.limitOrder(symbol, side, price, size));
+            placed.set(step.id, { symbol, side, filledSize: null, decimals: sizeDecimalsOf(size), orderId: extractOrderId(result) });
             logExecution({ type: "limit_order", exchange: adapter.name, symbol, side, size, price, status: "success", dryRun: false, meta: { planStep: step.id, clientId: step.clientId } });
             return result;
         }
         case "stop_order": {
             const triggerPrice = String(p.triggerPrice ?? "");
             const limitPrice = p.limitPrice ? String(p.limitPrice) : undefined;
-            return adapter.stopOrder(symbol, side, size, triggerPrice, { limitPrice, reduceOnly: !!p.reduceOnly });
+            const result = await sendRestingOrder(adapter, `stop ${side} ${size} ${symbol} @ ${triggerPrice}`, () => adapter.stopOrder(symbol, side, size, triggerPrice, {
+                limitPrice, reduceOnly: !!p.reduceOnly,
+                // Market triggers carry the resolved bound (protection-priced on Lighter / Arcus; native triggers ignore it).
+                ...(limitPrice === undefined ? { slippage: resolveAdapterSlippage(adapter, null) } : {}),
+            }));
+            placed.set(step.id, { symbol, side, filledSize: null, decimals: sizeDecimalsOf(size), orderId: extractOrderId(result) });
+            return result;
         }
         case "cancel_order": {
             return adapter.cancelOrder(symbol, String(p.orderId ?? ""));
@@ -211,14 +292,23 @@ async function executeStep(adapter, step, log) {
             return adapter.setLeverage(symbol, lev, mode);
         }
         case "close_position": {
+            invalidateCache("acct"); // size the reduce-only close from a fresh read, never a cached position
             const positions = await adapter.getPositions();
             const pos = positions.find(pp => symbolMatch(pp.symbol, symbol));
             if (!pos)
                 throw new Error(`No position found for ${symbol}`);
             const closeSide = pos.side === "long" ? "sell" : "buy";
-            const result = await adapter.marketOrder(pos.symbol, closeSide, pos.size);
-            logExecution({ type: "market_order", exchange: adapter.name, symbol, side: closeSide, size: pos.size, status: "success", dryRun: false, meta: { planStep: step.id, action: "close_position" } });
-            return result;
+            // Size from the live position (abs), reduce-only: a stale / repeated close can never open
+            // or flip a position — the venue rejects it instead. Fill measured (ORDER_PENDING when unconfirmed).
+            // A partial close (venue-final IOC partial fills are accepted, §13.10 #4) gets ONE residual
+            // close (closePerpVerified); a residual still open fails the step with ORDER_PARTIAL.
+            const liveSize = pos.size.replace(/^-/, "");
+            const c = await closePerpVerified(adapter, adapter.name, pos.symbol, closeSide, liveSize);
+            logExecution({ type: "market_order", exchange: adapter.name, symbol, side: closeSide, size: liveSize, status: c.residual > 0 ? "failed" : "success", dryRun: false, meta: { planStep: step.id, action: "close_position", reduceOnly: true, filledSize: c.closed, residual: c.residual } });
+            if (c.residual > 0) {
+                throw new PerpError("ORDER_PARTIAL", `close_position ${pos.symbol}: closed ${c.closed} of ${liveSize}, ${c.residual} still open${c.note !== null ? ` (${c.note})` : ""}`, { exchange: adapter.name });
+            }
+            return { symbol: pos.symbol, side: closeSide, size: liveSize, closed: c.closed };
         }
         case "wait": {
             const ms = Number(p.ms ?? 1000);
@@ -248,33 +338,54 @@ async function executeStep(adapter, step, log) {
     }
 }
 /**
- * Attempt to rollback completed steps by performing inverse operations.
+ * Reverse completed steps (reverse order). A filled market order is closed reduce-only for
+ * its MEASURED fill (closePerpVerified, residual handled); a limit / stop order's resting
+ * orders are cancelled on that step's symbol only. A reversal that is rejected, unconfirmed
+ * or partial marks the step rollback_failed and quarantines the symbol. Steps on
+ * `skipSymbol` (an order whose outcome is unknown) are left untouched.
  */
-async function rollbackSteps(adapter, completedSteps, log) {
-    // Rollback in reverse order
+async function rollbackSteps(adapter, completedSteps, placed, skipSymbol, quarantine, log) {
     for (let i = completedSteps.length - 1; i >= 0; i--) {
         const step = completedSteps[i];
+        const order = placed.get(step.stepId);
+        if (order === undefined)
+            continue; // not an order step (cancel / leverage / checks / close_position): nothing to reverse
+        if (skipSymbol !== null && order.symbol === skipSymbol) {
+            log(`[rollback] Leaving ${step.stepId} (${order.symbol}) — the symbol has an order with unknown outcome (quarantined)`);
+            continue;
+        }
         try {
-            switch (step.action) {
-                case "market_order":
-                case "limit_order": {
-                    // Close the position that was opened
-                    // This is best-effort — market conditions may have changed
-                    log(`[rollback] Attempting to reverse ${step.action} ${step.stepId}`);
-                    // We'd need position info; just cancel any pending orders as safety measure
-                    await adapter.cancelAllOrders().catch(() => { });
-                    break;
+            if (order.filledSize !== null) {
+                const size = fillSizeString(order.filledSize, order.decimals);
+                if (!(Number(size) > 0))
+                    continue;
+                const closeSide = order.side === "buy" ? "sell" : "buy";
+                log(`[rollback] Reversing ${step.stepId}: reduce-only ${closeSide} ${size} ${order.symbol}`);
+                const c = await closePerpVerified(adapter, adapter.name, order.symbol, closeSide, size, { decimals: order.decimals });
+                if (c.residual > 0)
+                    throw new Error(`closed ${c.closed}; ${c.residual} still open${c.note !== null ? ` (${c.note})` : ""}`);
+            }
+            else {
+                // Resting limit / stop: cancel ONLY this step's order (never the user's other orders
+                // on the symbol). Any fill before the cancel is not reversed — the step is marked
+                // "cancelled" (not "rolled_back") and the log says to check the position.
+                if (order.orderId === null) {
+                    throw new Error(`no order id was returned for ${step.stepId}; cancel it manually (perp trade cancel ${order.symbol} <orderId>)`);
                 }
-                case "cancel_order":
-                case "cancel_all":
-                    // Can't un-cancel, skip
-                    break;
-                default:
-                    break;
+                log(`[rollback] Cancelling ${step.stepId} order ${order.orderId} on ${order.symbol}`);
+                await adapter.cancelOrder(order.symbol, order.orderId);
+                log(`[rollback] ${step.stepId}: any partial fill before the cancel is NOT reversed — check ${order.symbol} position`);
+                step.status = "cancelled";
+                continue;
             }
+            step.status = "rolled_back";
         }
         catch (err) {
-            log(`[rollback] Failed to rollback step ${step.stepId}: ${err instanceof Error ? err.message : err}`);
+            const message = extractErrorMessage(err);
+            log(`[rollback] Failed to rollback step ${step.stepId}: ${message}`);
+            step.status = "rollback_failed";
+            step.error = { code: isOutcomeUnknown(err) ? "ORDER_PENDING" : "ROLLBACK_FAILED", message };
+            quarantine(order.symbol, `rollback of step ${step.stepId} (${step.action} ${order.side} ${order.symbol}) ${isOutcomeUnknown(err) ? "unconfirmed" : "failed"}: ${message}`);
         }
     }
 }

package/dist/position-history.js

@@ -110,6 +110,15 @@ export function getPositionStats(opts) {
     for (const r of records) {
         stats.totalTrades++;
         const pnl = Number(r.realizedPnl ?? 0);
+        // Rule #2 (qa/2026-05-16 extension): a non-finite realizedPnl from a
+        // corrupt history row would propagate NaN into totalPnl / averages and
+        // break the entire stats report. Surface the bad row and skip its PnL
+        // contribution (the trade is still counted but excluded from PnL math
+        // so the operator sees the row count vs. expected and can investigate).
+        if (!Number.isFinite(pnl)) {
+            process.stderr.write(`[position-history] skipping non-finite realizedPnl for ${r.symbol ?? "<unknown>"} on ${r.exchange ?? "<unknown>"}: ${JSON.stringify(r.realizedPnl)}\n`);
+            continue;
+        }
         if (pnl > 0)
             stats.wins++;
         else if (pnl < 0)
@@ -150,6 +159,10 @@ export function getPositionStats(opts) {
     const symbolWins = {};
     for (const r of records) {
         const pnl = Number(r.realizedPnl ?? 0);
+        // Same guard as above — silently skipping NaN here keeps win-rate
+        // attribution consistent with the totals computed in the main loop.
+        if (!Number.isFinite(pnl))
+            continue;
         if (pnl > 0) {
             symbolWins[r.symbol] = (symbolWins[r.symbol] ?? 0) + 1;
         }

package/dist/rebalance.d.ts

@@ -1,4 +1,7 @@
 import type { ExchangeAdapter } from "./exchanges/index.js";
+import "./exchanges/venues/index.js";
+/** Throws NO_BRIDGE_ROUTE when the venue's funds live where no bridge route exists. */
+export declare function assertBridgeRoute(exchange: string): void;
 /**
  * Cross-exchange rebalancing engine.
  *
@@ -45,9 +48,30 @@ export declare function computeRebalancePlan(snapshots: ExchangeBalanceSnapshot[
     reserve?: number;
 }): RebalancePlan;
 /**
- * Check if an exchange has enough available balance for a given trade size.
+ * Headroom over the initial margin an arb leg needs before it is entered: covers taker fees,
+ * the slippage bound on the market entry, venue margin rounding and a mark move before the
+ * second leg fills (the leg must not be at maintenance margin right after entry).
  */
-export declare function hasEnoughBalance(snapshots: ExchangeBalanceSnapshot[], exchange: string, requiredUsd: number, marginBuffer?: number): boolean;
+export declare const ARB_MARGIN_BUFFER = 1.5;
+/**
+ * Margin a leg of `notionalUsd` needs at `leverage` (the leverage the venue applies to the market
+ * — the arb does not change it), × ARB_MARGIN_BUFFER. Leverage unknown (null: the venue exposes no
+ * per-market setting) → the 1x requirement (the full notional): the most margin any leverage can
+ * need, so the check never under-states it.
+ */
+export declare function requiredArbMargin(notionalUsd: number, leverage: number | null, buffer?: number): number;
+/**
+ * Check if an exchange has enough available balance to open a leg of `notionalUsd` at
+ * `leverage` (requiredArbMargin). No balance snapshot for the exchange → false.
+ */
+export declare function hasEnoughBalance(snapshots: ExchangeBalanceSnapshot[], exchange: string, notionalUsd: number, leverage: number | null, marginBuffer?: number): boolean;
+/**
+ * The leverage `adapter` applies to `symbol`: adapter.marketLeverage(symbol) where the venue has a
+ * per-symbol read (Hyperliquid activeAssetData, Pacifica /account/settings), else the
+ * adapter.getMarketSettings() row (Aster, Lighter, Arcus). null when neither lists the symbol;
+ * a failed read throws.
+ */
+export declare function marketLeverageOf(adapter: object, symbol: string): Promise<number | null>;
 /**
  * Describe the bridge route for a rebalance move.
  */

package/dist/rebalance.js

@@ -1,3 +1,21 @@
+import { PerpError } from "./errors.js";
+import { getVenue, tryResolveVenueId } from "./exchanges/venue.js";
+import "./exchanges/venues/index.js";
+/** Settlement chains with no withdraw → bridge → deposit route in this CLI (design §10.10). */
+const NO_ROUTE_CHAINS = new Set(["robinhood", "offchain"]);
+/** Throws NO_BRIDGE_ROUTE when the venue's funds live where no bridge route exists. */
+export function assertBridgeRoute(exchange) {
+    const id = tryResolveVenueId(exchange);
+    if (id === null)
+        return; // not a venue name — the existing "unknown route" handling applies
+    const def = getVenue(id);
+    const chain = def.networks.mainnet.settlementChain;
+    if (NO_ROUTE_CHAINS.has(chain)) {
+        throw new PerpError("NO_BRIDGE_ROUTE", `${def.displayName} settles on "${chain}"; cross-venue rebalancing has no route there`, {
+            remediation: `Exclude ${def.id} from --exchanges and move funds for it manually`,
+        });
+    }
+}
 import { EXCHANGE_TO_CHAIN } from "./bridge-engine.js";
 // Re-export for backward compat
 const EXCHANGE_CHAINS = Object.fromEntries(Object.entries(EXCHANGE_TO_CHAIN).map(([ex, chain]) => [ex, { chain }]));
@@ -8,12 +26,35 @@ export async function fetchAllBalances(adapters) {
     const entries = [...adapters.entries()];
     const results = await Promise.allSettled(entries.map(async ([name, adapter]) => {
         const bal = await adapter.getBalance();
+        // Strict policy (qa/2026-05-16): empty string is corruption, not
+        // "venue stringified zero". A truly absent field must surface as
+        // undefined/null at the adapter layer, not "". An empty string here
+        // would coerce to 0 via Number("") and silently propagate a $0
+        // balance into the plan — exactly the Rule #2 silent-substitution
+        // hole this audit cycle is closing.
+        if (bal.equity === "" || bal.available === "" || bal.marginUsed === "" || bal.unrealizedPnl === "") {
+            throw new PerpError("EXCHANGE_ERROR", `${name} returned empty-string balance field: equity="${bal.equity}" available="${bal.available}" marginUsed="${bal.marginUsed}" unrealizedPnl="${bal.unrealizedPnl}"`, { exchange: name });
+        }
+        const equity = Number(bal.equity);
+        const available = Number(bal.available);
+        const marginUsed = Number(bal.marginUsed);
+        const unrealizedPnl = Number(bal.unrealizedPnl);
+        // Rule #2: rebalance plan computes sums and per-exchange targets.
+        // A NaN value would silently propagate into the plan output and the
+        // execute step would attempt nonsense moves. Reject upfront so the
+        // affected exchange falls out of `Promise.allSettled` (filtered to
+        // fulfilled below) and the user sees a partial result instead of a
+        // corrupt plan.
+        if (!Number.isFinite(equity) || !Number.isFinite(available) ||
+            !Number.isFinite(marginUsed) || !Number.isFinite(unrealizedPnl)) {
+            throw new PerpError("EXCHANGE_ERROR", `${name} returned non-finite balance: equity=${bal.equity} available=${bal.available} marginUsed=${bal.marginUsed} unrealizedPnl=${bal.unrealizedPnl}`, { exchange: name });
+        }
         return {
             exchange: name,
-            equity: Number(bal.equity),
-            available: Number(bal.available),
-            marginUsed: Number(bal.marginUsed),
-            unrealizedPnl: Number(bal.unrealizedPnl),
+            equity,
+            available,
+            marginUsed,
+            unrealizedPnl,
         };
     }));
     return results
@@ -62,6 +103,8 @@ export function computeRebalancePlan(snapshots, opts = {}) {
             const moveAmt = Math.min(remaining, Math.abs(deficitAmt));
             if (moveAmt < minMove)
                 continue;
+            assertBridgeRoute(fromEx);
+            assertBridgeRoute(toEx);
             moves.push({
                 from: fromEx,
                 to: toEx,
@@ -84,18 +127,54 @@ export function computeRebalancePlan(snapshots, opts = {}) {
     };
 }
 /**
- * Check if an exchange has enough available balance for a given trade size.
+ * Headroom over the initial margin an arb leg needs before it is entered: covers taker fees,
+ * the slippage bound on the market entry, venue margin rounding and a mark move before the
+ * second leg fills (the leg must not be at maintenance margin right after entry).
+ */
+export const ARB_MARGIN_BUFFER = 1.5;
+/**
+ * Margin a leg of `notionalUsd` needs at `leverage` (the leverage the venue applies to the market
+ * — the arb does not change it), × ARB_MARGIN_BUFFER. Leverage unknown (null: the venue exposes no
+ * per-market setting) → the 1x requirement (the full notional): the most margin any leverage can
+ * need, so the check never under-states it.
+ */
+export function requiredArbMargin(notionalUsd, leverage, buffer = ARB_MARGIN_BUFFER) {
+    const lev = leverage !== null && Number.isFinite(leverage) && leverage >= 1 ? leverage : 1;
+    return (notionalUsd / lev) * buffer;
+}
+/**
+ * Check if an exchange has enough available balance to open a leg of `notionalUsd` at
+ * `leverage` (requiredArbMargin). No balance snapshot for the exchange → false.
  */
-export function hasEnoughBalance(snapshots, exchange, requiredUsd, marginBuffer = 1.5) {
+export function hasEnoughBalance(snapshots, exchange, notionalUsd, leverage, marginBuffer = ARB_MARGIN_BUFFER) {
     const snap = snapshots.find((s) => s.exchange === exchange);
     if (!snap)
         return false;
-    return snap.available >= requiredUsd * marginBuffer;
+    return snap.available >= requiredArbMargin(notionalUsd, leverage, marginBuffer);
+}
+/**
+ * The leverage `adapter` applies to `symbol`: adapter.marketLeverage(symbol) where the venue has a
+ * per-symbol read (Hyperliquid activeAssetData, Pacifica /account/settings), else the
+ * adapter.getMarketSettings() row (Aster, Lighter, Arcus). null when neither lists the symbol;
+ * a failed read throws.
+ */
+export async function marketLeverageOf(adapter, symbol) {
+    const one = adapter.marketLeverage;
+    if (typeof one === "function")
+        return one.call(adapter, symbol);
+    const read = adapter.getMarketSettings;
+    if (typeof read !== "function")
+        return null;
+    const norm = (x) => x.toUpperCase().replace(/-PERP$/, "").replace(/^[^:]+:/, "");
+    const row = (await read.call(adapter)).find(r => norm(r.symbol) === norm(symbol));
+    return row !== undefined && row.leverage >= 1 ? row.leverage : null;
 }
 /**
  * Describe the bridge route for a rebalance move.
  */
 export function describeBridgeRoute(move) {
+    assertBridgeRoute(move.from);
+    assertBridgeRoute(move.to);
     const from = EXCHANGE_CHAINS[move.from];
     const to = EXCHANGE_CHAINS[move.to];
     if (!from || !to)