hyperliquid-prime 0.1.3 → 0.1.5

package/dist/collateral/manager.js

@@ -1,4 +1,263 @@
 import { FillSimulator } from "../router/simulator.js";
+import { formatPrice } from "@nktkas/hyperliquid/utils";
+const KNOWN_STABLE_COLLATERAL = new Set([
+    "USDC",
+    "USDT",
+    "USDT0",
+    "USDH",
+    "USDE",
+    "USDS",
+    "USDB",
+    "USDD",
+    "DAI",
+    "FDUSD",
+    "PYUSD",
+]);
+const DEFAULT_QUOTE_TOKEN_PRIORITY = [
+    "USDC",
+    "USDT",
+    "USDT0",
+    "USDH",
+    "USDE",
+    "USDS",
+    "USDB",
+    "USDD",
+    "DAI",
+    "FDUSD",
+    "PYUSD",
+];
+function normalizeToken(value) {
+    return value.trim().toUpperCase();
+}
+function parsePerpSpendableStableUsd(state) {
+    const totalRawUsdRaw = parseFloat(String(state.marginSummary?.totalRawUsd ?? ""));
+    const withdrawableRaw = parseFloat(String(state.withdrawable ?? ""));
+    const hasPositiveTotalRawUsd = Number.isFinite(totalRawUsdRaw) && totalRawUsdRaw > 0;
+    if (Number.isFinite(withdrawableRaw) && hasPositiveTotalRawUsd) {
+        // Use the more conservative spendable estimate for USDC collateral planning.
+        return Math.max(0, Math.min(withdrawableRaw, totalRawUsdRaw));
+    }
+    if (Number.isFinite(withdrawableRaw))
+        return Math.max(0, withdrawableRaw);
+    if (hasPositiveTotalRawUsd)
+        return Math.max(0, totalRawUsdRaw);
+    const accountValueRaw = parseFloat(String(state.marginSummary?.accountValue ?? "0"));
+    if (Number.isFinite(accountValueRaw))
+        return Math.max(0, accountValueRaw);
+    return 0;
+}
+function inferPerpUsdcBalanceFromSpot(params) {
+    const spotUsdcBalance = Math.max(0, params.spotBalances.get("USDC") ?? 0);
+    let nonUsdcStableSpotBalance = 0;
+    for (const [coinRaw, totalRaw] of params.spotBalances.entries()) {
+        const coin = normalizeToken(coinRaw);
+        if (coin === "USDC" || !isStableCollateralToken(coin))
+            continue;
+        const total = Number.isFinite(totalRaw) ? Math.max(0, totalRaw) : 0;
+        nonUsdcStableSpotBalance += total;
+    }
+    const spendableStableUsd = Number.isFinite(params.spendableStableUsd)
+        ? Math.max(0, params.spendableStableUsd)
+        : 0;
+    const inferredPerp = Math.max(0, spendableStableUsd - nonUsdcStableSpotBalance - spotUsdcBalance);
+    return {
+        perpUsdcBalance: inferredPerp,
+        spotUsdcBalance,
+        nonUsdcStableSpotBalance,
+    };
+}
+function isStableCollateralToken(value) {
+    const token = normalizeToken(value);
+    if (KNOWN_STABLE_COLLATERAL.has(token))
+        return true;
+    return token.startsWith("USD");
+}
+function normalizeSzDecimals(value) {
+    if (!Number.isFinite(value ?? NaN))
+        return 6;
+    return Math.max(0, Math.min(12, Math.floor(value ?? 6)));
+}
+function quantizeSize(value, szDecimals) {
+    if (!Number.isFinite(value) || value <= 0)
+        return 0;
+    const decimals = normalizeSzDecimals(szDecimals);
+    const factor = 10 ** decimals;
+    return Math.ceil((value - Number.EPSILON) * factor) / factor;
+}
+function toSizeString(value, decimals) {
+    if (!Number.isFinite(value) || value <= 0)
+        return "0";
+    return value.toFixed(normalizeSzDecimals(decimals)).replace(/\.?0+$/, "");
+}
+function formatSpotLimitPrice(price, szDecimals) {
+    const safePrice = Number.isFinite(price) ? Math.max(price, 0) : 0;
+    if (safePrice <= 0) {
+        throw new Error("Invalid spot limit price after slippage adjustment.");
+    }
+    return formatPrice(safePrice, normalizeSzDecimals(szDecimals), "spot");
+}
+function quotePriority(token, preferredQuotes) {
+    const normalized = normalizeToken(token);
+    const idx = preferredQuotes.indexOf(normalized);
+    if (idx >= 0)
+        return idx;
+    if (isStableCollateralToken(normalized))
+        return preferredQuotes.length;
+    return Number.POSITIVE_INFINITY;
+}
+function buildStableSourceBalances(spotBalances, perpUsdcBalance) {
+    const out = new Map();
+    for (const [coinRaw, totalRaw] of spotBalances.entries()) {
+        const coin = normalizeToken(coinRaw);
+        const total = Number.isFinite(totalRaw) ? Math.max(0, totalRaw) : 0;
+        if (total <= 0 || !isStableCollateralToken(coin))
+            continue;
+        out.set(coin, (out.get(coin) ?? 0) + total);
+    }
+    const perpUsdc = Number.isFinite(perpUsdcBalance) ? Math.max(0, perpUsdcBalance) : 0;
+    if (perpUsdc > 0) {
+        out.set("USDC", (out.get("USDC") ?? 0) + perpUsdc);
+    }
+    return out;
+}
+function consumeSourceBalance(sourceBalances, token, amount) {
+    const key = normalizeToken(token);
+    const available = sourceBalances.get(key) ?? 0;
+    sourceBalances.set(key, Math.max(0, available - Math.max(0, amount)));
+}
+function chooseSwapSourceToken(params) {
+    const target = normalizeToken(params.targetToken);
+    const preferred = params.preferredSource ? normalizeToken(params.preferredSource) : undefined;
+    const amountNeeded = Number.isFinite(params.amountNeeded) ? Math.max(0, params.amountNeeded) : 0;
+    const candidateEntries = [...params.sourceBalances.entries()]
+        .filter(([token, available]) => token !== target &&
+        available > 0 &&
+        isStableCollateralToken(token))
+        .sort((a, b) => {
+        const [tokenA, availableA] = a;
+        const [tokenB, availableB] = b;
+        const coversNeededA = availableA >= amountNeeded ? 1 : 0;
+        const coversNeededB = availableB >= amountNeeded ? 1 : 0;
+        if (coversNeededA !== coversNeededB)
+            return coversNeededB - coversNeededA;
+        const usdcPenaltyA = tokenA === "USDC" ? 1 : 0;
+        const usdcPenaltyB = tokenB === "USDC" ? 1 : 0;
+        if (usdcPenaltyA !== usdcPenaltyB)
+            return usdcPenaltyA - usdcPenaltyB;
+        if (availableA !== availableB)
+            return availableB - availableA;
+        return quotePriority(tokenA, DEFAULT_QUOTE_TOKEN_PRIORITY)
+            - quotePriority(tokenB, DEFAULT_QUOTE_TOKEN_PRIORITY);
+    });
+    if (candidateEntries.length > 0) {
+        return candidateEntries[0][0];
+    }
+    if (preferred && preferred !== target) {
+        return preferred;
+    }
+    return "USDC";
+}
+function isLikelyInsufficientBalanceError(message) {
+    return /insufficient|not enough|available|balance|margin/i.test(message);
+}
+function resolveSpotSwapMarket(tokenByIndex, pairs, targetToken, swapFrom) {
+    const target = normalizeToken(targetToken);
+    const from = normalizeToken(swapFrom);
+    const candidates = [];
+    for (const pair of pairs) {
+        if (pair.tokens.length < 2)
+            continue;
+        const base = tokenByIndex.get(pair.tokens[0]);
+        const quote = tokenByIndex.get(pair.tokens[1]);
+        if (!base || !quote)
+            continue;
+        const baseToken = normalizeToken(base.name);
+        const quoteToken = normalizeToken(quote.name);
+        if (baseToken === target && quoteToken === from) {
+            // target/swapFrom pair: buy base to receive target token.
+            candidates.push({
+                pair,
+                baseToken: base.name,
+                quoteToken: quote.name,
+                baseSzDecimals: base.szDecimals,
+                orientationRank: 0,
+            });
+            continue;
+        }
+        if (baseToken === from && quoteToken === target) {
+            // swapFrom/target pair: sell base to receive target token as quote.
+            candidates.push({
+                pair,
+                baseToken: base.name,
+                quoteToken: quote.name,
+                baseSzDecimals: base.szDecimals,
+                orientationRank: 1,
+            });
+        }
+    }
+    if (candidates.length === 0) {
+        const stableFallback = [
+            from,
+            ...DEFAULT_QUOTE_TOKEN_PRIORITY,
+        ].filter((token, index, values) => values.indexOf(token) === index);
+        for (const pair of pairs) {
+            if (pair.tokens.length < 2)
+                continue;
+            const base = tokenByIndex.get(pair.tokens[0]);
+            const quote = tokenByIndex.get(pair.tokens[1]);
+            if (!base || !quote)
+                continue;
+            if (normalizeToken(base.name) !== target)
+                continue;
+            if (quotePriority(quote.name, stableFallback) === Number.POSITIVE_INFINITY)
+                continue;
+            candidates.push({
+                pair,
+                baseToken: base.name,
+                quoteToken: quote.name,
+                baseSzDecimals: base.szDecimals,
+                orientationRank: 2,
+            });
+        }
+    }
+    if (candidates.length === 0) {
+        throw new Error(`No spot pair found for ${swapFrom}->${targetToken}`);
+    }
+    candidates.sort((a, b) => {
+        if (a.orientationRank !== b.orientationRank) {
+            return a.orientationRank - b.orientationRank;
+        }
+        if (Boolean(a.pair.isCanonical) !== Boolean(b.pair.isCanonical)) {
+            return a.pair.isCanonical ? -1 : 1;
+        }
+        return a.pair.index - b.pair.index;
+    });
+    const selected = candidates[0];
+    if (selected.orientationRank === 1) {
+        return {
+            pairId: selected.pair.name,
+            pairLabel: `${selected.baseToken}/${selected.quoteToken}`,
+            assetIndex: 10000 + selected.pair.index,
+            baseSzDecimals: selected.baseSzDecimals,
+            side: "sell",
+            priceSide: "bids",
+            sizeMultiplier: 1.01,
+            sizeDivisor: 1,
+            quoteToken: selected.quoteToken,
+        };
+    }
+    return {
+        pairId: selected.pair.name,
+        pairLabel: `${selected.baseToken}/${selected.quoteToken}`,
+        assetIndex: 10000 + selected.pair.index,
+        baseSzDecimals: selected.baseSzDecimals,
+        side: "buy",
+        priceSide: "asks",
+        sizeMultiplier: 1,
+        sizeDivisor: 1,
+        quoteToken: selected.quoteToken,
+    };
+}
 /**
  * CollateralManager handles two concerns:
  * 1. Estimation (read-only): What collateral swaps are needed and how much will they cost?
@@ -31,11 +290,26 @@ export class CollateralManager {
         const spotState = await this.provider.spotClearinghouseState(userAddress);
         const balanceMap = new Map();
         for (const b of spotState.balances) {
-            balanceMap.set(b.coin, parseFloat(b.total));
+            const parsed = parseFloat(b.total);
+            balanceMap.set(normalizeToken(b.coin), Number.isFinite(parsed) ? parsed : 0);
         }
         // Get perp balance (USDC is the perp native collateral)
         const perpState = await this.provider.clearinghouseState(userAddress);
-        const perpUsdcBalance = parseFloat(perpState.marginSummary.accountValue);
+        const spendableStableUsd = parsePerpSpendableStableUsd(perpState);
+        const { perpUsdcBalance, spotUsdcBalance, nonUsdcStableSpotBalance, } = inferPerpUsdcBalanceFromSpot({
+            spendableStableUsd,
+            spotBalances: balanceMap,
+        });
+        this.logger.warn({
+            user: userAddress,
+            accountValue: perpState.marginSummary?.accountValue,
+            totalRawUsd: perpState.marginSummary?.totalRawUsd,
+            withdrawable: perpState.withdrawable,
+            spendableStableUsd,
+            nonUsdcStableSpotBalance,
+            spotUsdcBalance,
+            plannedPerpUsdcAvailable: perpUsdcBalance,
+        }, "[debug] Collateral balance inputs");
         // Group allocations by collateral type
         const collateralNeeds = new Map();
         for (const alloc of allocations) {
@@ -43,76 +317,91 @@ export class CollateralManager {
             const amount = alloc.estimatedCost; // USD value needed
             collateralNeeds.set(token, (collateralNeeds.get(token) ?? 0) + amount);
         }
+        const sourceBalances = buildStableSourceBalances(balanceMap, perpUsdcBalance);
         const requirements = [];
         let swapsNeeded = false;
-        const swapShortfalls = new Map();
-        const tokenBalances = new Map();
-        for (const [token, amountNeeded] of collateralNeeds) {
-            if (token === "USDC") {
-                // USDC comes from perp balance automatically via abstraction
-                requirements.push({
-                    token,
-                    amountNeeded,
-                    currentBalance: perpUsdcBalance,
-                    shortfall: 0, // Abstraction handles USDC automatically
-                    swapFrom: "USDC",
-                    estimatedSwapCostBps: 0,
-                });
-                continue;
+        const swapCostJobs = [];
+        for (const [tokenRaw, amountNeeded] of collateralNeeds) {
+            const token = normalizeToken(tokenRaw);
+            const spotTokenBalance = balanceMap.get(token) ?? 0;
+            const currentBalance = token === "USDC"
+                ? perpUsdcBalance + spotTokenBalance
+                : spotTokenBalance;
+            const reservedExistingBalance = Math.min(amountNeeded, currentBalance);
+            if (reservedExistingBalance > 0) {
+                consumeSourceBalance(sourceBalances, token, reservedExistingBalance);
             }
-            // Non-USDC: needs to be in spot balance
-            const currentBalance = balanceMap.get(token) ?? 0;
             const shortfall = Math.max(0, amountNeeded - currentBalance);
-            tokenBalances.set(token, currentBalance);
+            let swapFrom = token;
             if (shortfall > 0) {
                 swapsNeeded = true;
-                swapShortfalls.set(token, shortfall);
+                const sourceAmountNeeded = shortfall * 1.01;
+                swapFrom = chooseSwapSourceToken({
+                    sourceBalances,
+                    targetToken: token,
+                    amountNeeded: sourceAmountNeeded,
+                });
+                consumeSourceBalance(sourceBalances, swapFrom, sourceAmountNeeded);
             }
-        }
-        const swapCostMap = new Map();
-        await Promise.all([...swapShortfalls.entries()].map(async ([token, shortfall]) => {
-            const swapCostBps = await this.estimateSwapCost("USDC", token, shortfall);
-            swapCostMap.set(token, swapCostBps);
-        }));
-        for (const [token, amountNeeded] of collateralNeeds) {
-            if (token === "USDC")
-                continue;
-            const currentBalance = tokenBalances.get(token) ?? 0;
-            const shortfall = Math.max(0, amountNeeded - currentBalance);
+            const requirementIndex = requirements.length;
             requirements.push({
                 token,
                 amountNeeded,
                 currentBalance,
                 shortfall,
-                swapFrom: "USDC",
-                estimatedSwapCostBps: swapCostMap.get(token) ?? 0,
+                swapFrom,
+                estimatedSwapCostBps: 0,
             });
+            if (shortfall > 0) {
+                swapCostJobs.push({
+                    index: requirementIndex,
+                    fromToken: swapFrom,
+                    toToken: token,
+                    amount: shortfall,
+                });
+            }
+        }
+        const swapCosts = await Promise.all(swapCostJobs.map(async (job) => {
+            const bps = await this.estimateSwapCost(job.fromToken, job.toToken, job.amount);
+            return { index: job.index, bps };
+        }));
+        for (const { index, bps } of swapCosts) {
+            requirements[index].estimatedSwapCostBps = bps;
         }
         const totalSwapCostBps = this.weightedSwapCost(requirements, allocations);
         return {
             requirements,
             totalSwapCostBps,
             swapsNeeded,
-            abstractionEnabled: false, // Will be checked during prepare()
+            // In trader app flow, unified abstraction is configured during setup.
+            // Avoid write-side abstraction changes during execution.
+            abstractionEnabled: true,
         };
     }
     /**
      * Estimate the cost in basis points to swap fromToken to toToken on the spot market.
      * Uses the spot L2Book to simulate the swap.
      */
-    async estimateSwapCost(_fromToken, toToken, amount) {
+    async estimateSwapCost(fromToken, toToken, amount) {
         try {
-            // Fetch the spot book for the target token
-            // On Hyperliquid, stablecoin pairs typically use @{index} format
-            // For now, try the token name directly
-            const book = await this.provider.l2Book(toToken);
+            const spotMeta = await this.provider.spotMeta();
+            const tokenByIndex = new Map();
+            for (const token of spotMeta.tokens) {
+                tokenByIndex.set(token.index, token);
+            }
+            const market = resolveSpotSwapMarket(tokenByIndex, spotMeta.universe, toToken, fromToken);
+            const byId = await this.provider.l2Book(market.pairId);
+            const needsAsks = market.priceSide === "asks";
+            const hasDepth = needsAsks ? byId.levels[1].length > 0 : byId.levels[0].length > 0;
+            const book = hasDepth || normalizeToken(market.pairId) === normalizeToken(market.pairLabel)
+                ? byId
+                : await this.provider.l2Book(market.pairLabel);
             if (book.levels[0].length === 0 && book.levels[1].length === 0) {
                 // No spot book available — return conservative default
                 return 50;
             }
-            // Simulate buying `amount` worth of toToken on the spot market
-            // Since stablecoins trade near $1, amount ≈ size
-            const sim = this.simulator.simulate(book, "buy", amount);
+            const simSide = market.side === "buy" ? "buy" : "sell";
+            const sim = this.simulator.simulate(book, simSide, amount);
             if (!sim) {
                 return 100; // Insufficient spot depth
             }
@@ -128,90 +417,197 @@ export class CollateralManager {
      * Execute collateral preparation: enable abstraction, perform swaps.
      * Call this before placing split orders.
      */
-    async prepare(plan, _userAddress) {
+    async prepare(plan, userAddress) {
         const swapsExecuted = [];
-        let abstractionWasEnabled = false;
+        const abstractionWasEnabled = false;
         try {
-            // Step 1: Enable DEX abstraction if not already enabled
-            if (!plan.abstractionEnabled) {
-                this.logger.info("Enabling DEX abstraction");
-                await this.provider.setDexAbstraction(true);
-                abstractionWasEnabled = true;
-            }
+            const signerAddress = this.provider.getSignerAddress?.();
+            const isAgentSession = Boolean(signerAddress && signerAddress.toLowerCase() !== userAddress.toLowerCase());
             const spotMeta = await this.provider.spotMeta();
-            const tokenByName = new Map(spotMeta.tokens.map((token) => [token.name, token]));
-            const pairByTokenIndex = new Map();
-            for (const pair of spotMeta.universe) {
-                for (const tokenIndex of pair.tokens) {
-                    if (!pairByTokenIndex.has(tokenIndex)) {
-                        pairByTokenIndex.set(tokenIndex, pair);
-                    }
-                }
+            const tokenByIndex = new Map();
+            for (const token of spotMeta.tokens) {
+                tokenByIndex.set(token.index, token);
+            }
+            const pairs = spotMeta.universe;
+            const spotState = await this.provider.spotClearinghouseState(userAddress);
+            const spotBalanceMap = new Map();
+            for (const balance of spotState.balances) {
+                const parsed = parseFloat(balance.total);
+                spotBalanceMap.set(normalizeToken(balance.coin), Number.isFinite(parsed) ? parsed : 0);
             }
+            const perpState = await this.provider.clearinghouseState(userAddress);
+            const spendableStableUsd = parsePerpSpendableStableUsd(perpState);
+            const { perpUsdcBalance } = inferPerpUsdcBalanceFromSpot({
+                spendableStableUsd,
+                spotBalances: spotBalanceMap,
+            });
+            const sourceBalances = buildStableSourceBalances(spotBalanceMap, perpUsdcBalance);
             // Step 2: Execute swaps for each requirement with shortfall
             for (const req of plan.requirements) {
-                if (req.shortfall <= 0 || req.token === "USDC")
+                if (req.shortfall <= 0)
                     continue;
-                // Move USDC from perp → spot
-                const transferAmount = req.shortfall * 1.01; // 1% buffer for slippage
-                this.logger.info({ amount: transferAmount, token: req.token }, "Transferring USDC to spot for swap");
-                await this.provider.usdClassTransfer(transferAmount, false);
+                const sourceAmountNeeded = req.shortfall * 1.01;
+                const swapFrom = chooseSwapSourceToken({
+                    sourceBalances,
+                    targetToken: req.token,
+                    amountNeeded: sourceAmountNeeded,
+                    preferredSource: req.swapFrom,
+                });
+                const market = resolveSpotSwapMarket(tokenByIndex, pairs, req.token, swapFrom);
                 // Place spot order to swap USDC → target token
                 // Spot orders use the same provider.placeOrder with spot asset indices
-                const spotBook = await this.provider.l2Book(req.token);
-                if (spotBook.levels[1].length === 0) {
+                const byId = await this.provider.l2Book(market.pairId);
+                const needsAsks = market.priceSide === "asks";
+                const hasDepth = needsAsks ? byId.levels[1].length > 0 : byId.levels[0].length > 0;
+                const spotBook = hasDepth || normalizeToken(market.pairId) === normalizeToken(market.pairLabel)
+                    ? byId
+                    : await this.provider.l2Book(market.pairLabel);
+                const topLevels = market.priceSide === "asks"
+                    ? spotBook.levels[1]
+                    : spotBook.levels[0];
+                if (topLevels.length === 0) {
                     return {
                         success: false,
                         swapsExecuted,
                         abstractionWasEnabled,
-                        error: `No spot liquidity for ${req.token}`,
+                        error: `No spot liquidity for ${req.token} (${market.pairLabel})`,
                     };
                 }
-                // Use best ask with slippage for limit price
-                const bestAsk = parseFloat(spotBook.levels[1][0].px);
-                const limitPrice = (bestAsk * 1.005).toFixed(6); // 0.5% slippage on swap
-                const spotToken = tokenByName.get(req.token);
-                if (!spotToken) {
+                const topPrice = parseFloat(topLevels[0].px);
+                if (!Number.isFinite(topPrice) || topPrice <= 0) {
                     return {
                         success: false,
                         swapsExecuted,
                         abstractionWasEnabled,
-                        error: `Spot token ${req.token} not found in spotMeta`,
+                        error: `Invalid spot top-of-book price for ${req.token} (${market.pairLabel})`,
                     };
                 }
-                // Spot asset index = 10000 + 2 * pair_index for the base token
-                // Find the pair that has this token
-                const pair = pairByTokenIndex.get(spotToken.index);
-                if (!pair) {
+                const limitPriceRaw = market.side === "buy"
+                    ? topPrice * 1.005
+                    : topPrice * 0.995;
+                const limitPrice = formatSpotLimitPrice(limitPriceRaw, market.baseSzDecimals);
+                const orderSize = market.side === "buy"
+                    ? req.shortfall
+                    : req.shortfall / topPrice;
+                const finalOrderSizeRaw = orderSize * market.sizeMultiplier / market.sizeDivisor;
+                const finalOrderSize = quantizeSize(finalOrderSizeRaw, market.baseSzDecimals);
+                const finalOrderSizeStr = toSizeString(finalOrderSize, market.baseSzDecimals);
+                if (!Number.isFinite(finalOrderSize) || finalOrderSize <= 0) {
                     return {
                         success: false,
                         swapsExecuted,
                         abstractionWasEnabled,
-                        error: `No spot pair found for ${req.token}`,
+                        error: `Invalid spot order size for ${req.token} (${market.pairLabel})`,
                     };
                 }
-                const spotAssetIndex = 10000 + 2 * pair.index;
-                this.logger.info({ token: req.token, size: req.shortfall, limitPrice, spotAssetIndex }, "Placing spot swap order");
-                const result = await this.provider.placeOrder({
-                    assetIndex: spotAssetIndex,
-                    isBuy: true,
-                    price: limitPrice,
-                    size: req.shortfall.toString(),
-                    reduceOnly: false,
-                    orderType: { limit: { tif: "Ioc" } },
-                });
-                const status = result.statuses[0];
+                if (finalOrderSizeStr === "0") {
+                    return {
+                        success: false,
+                        swapsExecuted,
+                        abstractionWasEnabled,
+                        error: `Spot order size rounded to zero for ${req.token} (${market.pairLabel})`,
+                    };
+                }
+                this.logger.info({
+                    from: swapFrom,
+                    token: req.token,
+                    size: finalOrderSize,
+                    side: market.side,
+                    limitPrice,
+                    spotAssetIndex: market.assetIndex,
+                    pair: market.pairLabel,
+                }, "Placing spot swap order");
+                const placeSwapOrder = async () => {
+                    const result = await this.provider.placeOrder({
+                        assetIndex: market.assetIndex,
+                        isBuy: market.side === "buy",
+                        price: limitPrice,
+                        size: finalOrderSizeStr,
+                        reduceOnly: false,
+                        orderType: { limit: { tif: "Ioc" } },
+                    });
+                    const status = result.statuses[0];
+                    if (status && typeof status === "object" && "error" in status) {
+                        throw new Error(`Spot swap rejected for ${req.token} (${market.pairLabel}): ${status.error} (side ${market.side}, px ${limitPrice}, size ${finalOrderSizeStr}, szDecimals ${market.baseSzDecimals})`);
+                    }
+                    if (status && typeof status === "string") {
+                        if (status === "waitingForFill" || status === "waitingForTrigger") {
+                            throw new Error(`Spot swap did not fill immediately for ${req.token} (${market.pairLabel}): ${status}`);
+                        }
+                        throw new Error(`Unknown spot swap status for ${req.token}: ${status}`);
+                    }
+                    if (status && typeof status === "object" && "filled" in status) {
+                        return status.filled.totalSz;
+                    }
+                    return "0";
+                };
                 let filled = "0";
-                if (status && typeof status === "object" && "filled" in status) {
-                    filled = status.filled.totalSz;
+                try {
+                    filled = await placeSwapOrder();
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    if (swapFrom !== "USDC" || !isLikelyInsufficientBalanceError(message)) {
+                        return {
+                            success: false,
+                            swapsExecuted,
+                            abstractionWasEnabled,
+                            error: message,
+                        };
+                    }
+                    if (isAgentSession) {
+                        return {
+                            success: false,
+                            swapsExecuted,
+                            abstractionWasEnabled,
+                            error: `Spot swap for ${req.token} failed (insufficient spot USDC) and ` +
+                                "usdClassTransfer requires master-wallet signing. " +
+                                "Transfer USDC from Perp to Spot manually or use the master wallet.",
+                        };
+                    }
+                    this.logger.info({ amount: sourceAmountNeeded, token: req.token }, "Transferring USDC to spot for swap fallback");
+                    await this.provider.usdClassTransfer(sourceAmountNeeded, false);
+                    filled = await placeSwapOrder();
                 }
+                consumeSourceBalance(sourceBalances, swapFrom, sourceAmountNeeded);
                 swapsExecuted.push({
-                    from: req.swapFrom,
+                    from: swapFrom,
                     to: req.token,
                     amount: req.shortfall.toString(),
                     filled,
                 });
             }
+            // Post-swap balance assertion: verify each required token's balance
+            // meets the needed amount after swaps completed.
+            if (swapsExecuted.length > 0) {
+                const postSwapSpotState = await this.provider.spotClearinghouseState(userAddress);
+                const postSwapBalances = new Map();
+                for (const b of postSwapSpotState.balances) {
+                    const parsed = parseFloat(b.total);
+                    postSwapBalances.set(normalizeToken(b.coin), Number.isFinite(parsed) ? parsed : 0);
+                }
+                for (const req of plan.requirements) {
+                    if (req.shortfall <= 0)
+                        continue;
+                    const postBalance = postSwapBalances.get(normalizeToken(req.token)) ?? 0;
+                    // Allow 2% tolerance for rounding, slippage, and fees
+                    const threshold = req.amountNeeded * 0.98;
+                    if (postBalance < threshold) {
+                        this.logger.warn({
+                            token: req.token,
+                            expected: req.amountNeeded,
+                            actual: postBalance,
+                            threshold,
+                        }, "Post-swap balance below required threshold");
+                        return {
+                            success: false,
+                            swapsExecuted,
+                            abstractionWasEnabled,
+                            error: `Post-swap balance for ${req.token} is ${postBalance.toFixed(2)}, need ${req.amountNeeded.toFixed(2)} (${((postBalance / req.amountNeeded) * 100).toFixed(1)}% of required)`,
+                        };
+                    }
+                }
+            }
             return {
                 success: true,
                 swapsExecuted,