perp-cli 0.12.15 → 0.14.0

package/dist/exchanges/hyperliquid-spot.d.ts

@@ -6,9 +6,10 @@
  *
  * Composes with HyperliquidAdapter for signing and API access.
  */
-import type { SpotAdapter, SpotMarketInfo, SpotBalance } from "./spot-interface.js";
+import type { SpotAdapter, SpotMarketInfo, SpotBalance, SpotHoldingPrice, SpotHoldingPricesCapable } from "./spot-interface.js";
+import type { ResolvedSlippage } from "./slippage.js";
 import type { HyperliquidAdapter } from "./hyperliquid.js";
-export declare class HyperliquidSpotAdapter implements SpotAdapter {
+export declare class HyperliquidSpotAdapter implements SpotAdapter, SpotHoldingPricesCapable {
     readonly name = "hyperliquid";
     private _hl;
     private _spotAssetMap;
@@ -16,29 +17,67 @@ export declare class HyperliquidSpotAdapter implements SpotAdapter {
     private _spotDecimals;
     private _spotCanonical;
     private _initialized;
+    private _outcome;
     private _cachedMetaCtx;
     constructor(hlAdapter: HyperliquidAdapter);
     /** Load spot metadata from the Hyperliquid spot API */
     init(): Promise<void>;
     private _loadSpotMeta;
     getSpotMarkets(): Promise<SpotMarketInfo[]>;
+    /**
+     * Prices of held HIP-4 outcome tokens (`+<encoding>` balance rows — not spot markets) for valuation:
+     * the outcome side's mid in the outcome's quote token (HyperliquidOutcomeAdapter.getBalanceCoinPrices).
+     * Other tokens are not returned (they stay unpriced).
+     */
+    getHoldingPrices(tokens: readonly string[]): Promise<SpotHoldingPrice[]>;
     getSpotOrderbook(symbol: string): Promise<{
         bids: [string, string][];
         asks: [string, string][];
     }>;
     getSpotBalances(): Promise<SpotBalance[]>;
-    spotMarketOrder(symbol: string, side: "buy" | "sell", size: string): Promise<unknown>;
+    /** Uncached read (bypasses the shared acct: TTL cache) — fill measurement / verification. */
+    getSpotBalancesFresh(): Promise<SpotBalance[]>;
+    private _spotBalances;
+    spotMarketOrder(symbol: string, side: "buy" | "sell", size: string, opts: {
+        slippage: ResolvedSlippage;
+    }): Promise<unknown>;
+    /** Definite IOC outcome of a raw spot order response (same contract as HyperliquidAdapter.iocOutcomeOf). */
+    iocOutcomeOf(raw: unknown): {
+        filledSize: string;
+        final: true;
+    } | null;
     spotLimitOrder(symbol: string, side: "buy" | "sell", price: string, size: string, opts?: {
         tif?: string;
     }): Promise<unknown>;
+    /**
+     * Open spot orders (info `openOrders`, spot coins only: "@<spotIndex>" or "PURR/USDC").
+     * Symbols are "BASE/QUOTE" from spot meta; a coin missing from meta → EXCHANGE_ERROR (never guessed).
+     */
+    getSpotOpenOrders(symbol: string | null): Promise<Array<{
+        orderId: string;
+        symbol: string;
+        side: "buy" | "sell";
+        price: string;
+        size: string;
+        filled: string;
+    }>>;
     spotCancelOrder(symbol: string, orderId: string): Promise<unknown>;
     /**
      * Transfer USDC between perp and spot accounts.
-     * HL uses separate balances — spot buys require USDC in the spot account.
-     * Uses SDK's transferBetweenSpotAndPerp (userSignedAction, not L1 action).
+     * HL uses separate balances (standard mode) — spot buys require USDC in the spot account.
      */
     transferUsdcToSpot(amount: number): Promise<unknown>;
     transferUsdcToPerp(amount: number): Promise<unknown>;
+    /**
+     * Spot↔perp USDC move by the active signer tier: an agent signs the L1
+     * `agentSendAsset` (agents cannot sign user-signed actions); the master signs
+     * `usdClassTransfer`. No signer → NO_SIGNER_AVAILABLE from the adapter.
+     */
+    private _moveUsdc;
+    /** SpotTransferCapable (§12.4 #4): USDC only; an `err` response is thrown, not returned. */
+    transferToSpot(amount: string, asset: string): Promise<unknown>;
+    transferToPerp(amount: string, asset: string): Promise<unknown>;
+    private _checkedTransfer;
     /** Get the spot asset index (without the 10000 offset) */
     getSpotIndex(base: string): number | undefined;
     /** Get spot size decimals for a base token — from API data, not hardcoded */

package/dist/exchanges/hyperliquid-spot.js

@@ -6,19 +6,15 @@
  *
  * Composes with HyperliquidAdapter for signing and API access.
  */
+import { HyperliquidOutcomeAdapter } from "./hyperliquid-outcome.js";
 import { PERP_TO_SPOT_MAP, SPOT_PERP_TOKEN_MAP } from "./spot-interface.js";
-/** HL official price rounding: 5 significant figures, max 8 decimals for spot */
-function hlRoundPrice(px, szDecimals) {
-    const MAX_DECIMALS = 8; // spot uses 8 (perp uses 6)
-    if (px > 100_000)
-        return String(Math.round(px));
-    const sig5 = Number(px.toPrecision(5));
-    const priceDec = Math.max(0, MAX_DECIMALS - szDecimals);
-    return Number(sig5.toFixed(priceDec)).toString();
-}
-/** HL official size rounding */
-function hlRoundSize(sz, szDecimals) {
-    return sz.toFixed(szDecimals);
+import { assertHlAppliedBps, hlIocOutcome, hlProtectionPrice, hlRequirePriceOnGrid, hlSizeStep, hlTif } from "./hyperliquid.js";
+import { floorSize } from "./precision.js";
+import { PerpError, isDefiniteOrderFailure, isTransportFailure, orderNotSent, orderOutcomeUnknown } from "../errors.js";
+import { invalidateCache } from "../cache.js";
+/** HL size: floored to the szDecimals lot (never rounded up past the request); 0 → SIZE_TOO_SMALL. */
+function hlRoundSize(size, szDecimals) {
+    return floorSize(size, hlSizeStep(szDecimals));
 }
 export class HyperliquidSpotAdapter {
     name = "hyperliquid";
@@ -28,6 +24,7 @@ export class HyperliquidSpotAdapter {
     _spotDecimals = new Map();
     _spotCanonical = new Map(); // "PURR" → true, "UBTC" → false
     _initialized = false;
+    _outcome = null;
     _cachedMetaCtx = null;
     constructor(hlAdapter) {
         this._hl = hlAdapter;
@@ -72,10 +69,11 @@ export class HyperliquidSpotAdapter {
                     continue;
                 this._spotAssetMap.set(key, u.index);
                 this._spotAssetReverse.set(u.index, key);
-                this._spotDecimals.set(key, {
-                    size: tokenSzDecimals.get(baseTokenIndex) ?? 2,
-                    price: 6,
-                });
+                // Rule #2: no assumed szDecimals — a token without one has no decimals entry and
+                // its orders are refused (SYMBOL_NOT_FOUND) instead of being sized on a guess.
+                const szDecimals = tokenSzDecimals.get(baseTokenIndex);
+                if (szDecimals !== undefined)
+                    this._spotDecimals.set(key, { size: szDecimals, price: Math.max(0, 8 - szDecimals) }); // HL spot price grid: max 8 − szDecimals decimals
                 this._spotCanonical.set(key, u.isCanonical === true);
             }
         }
@@ -85,48 +83,67 @@ export class HyperliquidSpotAdapter {
     }
     async getSpotMarkets() {
         await this.init();
-        try {
-            // Reuse cached metaCtx from init, or fetch fresh if cache expired
-            const metaCtx = this._cachedMetaCtx
-                ?? await this._infoPost({ type: "spotMetaAndAssetCtxs" });
-            if (!metaCtx?.[0]?.universe)
-                return [];
-            const tokenNames = new Map();
-            const tokenSzDec = new Map();
-            for (const t of metaCtx[0].tokens ?? []) {
-                tokenNames.set(t.index, t.name);
-                if (t.szDecimals !== undefined)
-                    tokenSzDec.set(t.index, t.szDecimals);
-            }
-            // Fetch accurate mid prices from allMids (markPx in metaCtx is unreliable for spot)
-            const allMids = await this._infoPost({ type: "allMids" });
-            const usdcTokenIndex = metaCtx[0].tokens?.find(t => t.name === "USDC")?.index ?? 0;
-            const markets = [];
-            for (const u of metaCtx[0].universe) {
-                // Only USDC-quoted pairs
-                if (u.tokens[1] !== usdcTokenIndex)
-                    continue;
-                const baseToken = tokenNames.get(u.tokens[0]) ?? "";
-                if (!baseToken)
-                    continue;
-                // Price from allMids using universe.name (e.g., "PURR/USDC" or "@107")
-                const midPrice = allMids[u.name] ?? "0";
-                const spotDec = this._spotDecimals.get(baseToken.toUpperCase());
-                markets.push({
-                    symbol: `${baseToken}/USDC`,
-                    baseToken,
-                    quoteToken: "USDC",
-                    markPrice: midPrice,
-                    volume24h: "0",
-                    sizeDecimals: spotDec?.size ?? tokenSzDec.get(u.tokens[0]) ?? 2,
-                    priceDecimals: spotDec?.price ?? 6,
-                });
-            }
-            return markets;
-        }
-        catch {
+        // Rule #2: no catch→[]. A failed spotMetaAndAssetCtxs/allMids fetch must throw,
+        // not be coerced to an empty markets list (which reads as "this venue has no spot
+        // markets" and silently disables spot-perp arb discovery/sizing).
+        // Reuse cached metaCtx from init, or fetch fresh if cache expired.
+        const metaCtx = this._cachedMetaCtx
+            ?? await this._infoPost({ type: "spotMetaAndAssetCtxs" });
+        if (!metaCtx?.[0]?.universe)
             return [];
+        const tokenNames = new Map();
+        const tokenSzDec = new Map();
+        for (const t of metaCtx[0].tokens ?? []) {
+            tokenNames.set(t.index, t.name);
+            if (t.szDecimals !== undefined)
+                tokenSzDec.set(t.index, t.szDecimals);
+        }
+        // Fetch accurate mid prices from allMids (markPx in metaCtx is unreliable for spot)
+        const allMids = await this._infoPost({ type: "allMids" });
+        const usdcTokenIndex = metaCtx[0].tokens?.find(t => t.name === "USDC")?.index ?? 0;
+        const markets = [];
+        for (const [ui, u] of metaCtx[0].universe.entries()) {
+            // Only USDC-quoted pairs
+            if (u.tokens[1] !== usdcTokenIndex)
+                continue;
+            const baseToken = tokenNames.get(u.tokens[0]) ?? "";
+            if (!baseToken)
+                continue;
+            // Price from allMids using universe.name (e.g., "PURR/USDC" or "@107")
+            const midPrice = allMids[u.name] ?? "0";
+            const spotDec = this._spotDecimals.get(baseToken.toUpperCase());
+            const sizeDecimals = spotDec?.size ?? tokenSzDec.get(u.tokens[0]);
+            // Rule #2: a market without a published szDecimals is not listed (never sized on a guess).
+            if (sizeDecimals === undefined)
+                continue;
+            markets.push({
+                symbol: `${baseToken}/USDC`,
+                baseToken,
+                quoteToken: "USDC",
+                markPrice: midPrice,
+                // asset ctxs are index-aligned with universe; dayNtlVlm = 24h quote volume
+                volume24h: metaCtx[1]?.[ui]?.dayNtlVlm !== undefined ? String(metaCtx[1][ui].dayNtlVlm) : null,
+                sizeDecimals,
+                // HL spot price grid: at most 8 − szDecimals decimals (venue rule) — derived, never a fixed guess.
+                priceDecimals: spotDec !== undefined ? spotDec.price : Math.max(0, 8 - sizeDecimals),
+            });
         }
+        return markets;
+    }
+    /**
+     * Prices of held HIP-4 outcome tokens (`+<encoding>` balance rows — not spot markets) for valuation:
+     * the outcome side's mid in the outcome's quote token (HyperliquidOutcomeAdapter.getBalanceCoinPrices).
+     * Other tokens are not returned (they stay unpriced).
+     */
+    async getHoldingPrices(tokens) {
+        const coins = tokens.filter(t => /^\+\d+$/.test(t));
+        if (coins.length === 0)
+            return [];
+        if (this._outcome === null)
+            this._outcome = new HyperliquidOutcomeAdapter(this._hl);
+        return (await this._outcome.getBalanceCoinPrices(coins)).map(p => ({
+            token: p.coin, quoteToken: p.quoteToken, markPrice: p.quoteToken === null ? null : p.mid,
+        }));
     }
     async getSpotOrderbook(symbol) {
         await this.init();
@@ -151,86 +168,245 @@ export class HyperliquidSpotAdapter {
         };
     }
     async getSpotBalances() {
+        return this._spotBalances(false);
+    }
+    /** Uncached read (bypasses the shared acct: TTL cache) — fill measurement / verification. */
+    async getSpotBalancesFresh() {
+        return this._spotBalances(true);
+    }
+    async _spotBalances(fresh) {
+        // Rule #2: no catch→[]. A failed spotClearinghouseState fetch must surface
+        // honestly — an empty list is indistinguishable from a genuinely empty wallet
+        // and silently drives wrong USDC-transfer sizing / false post-fill verification
+        // in the funding-arb bot (and a misleading empty holdings table).
+        // Reuse cached spot clearinghouse state (shared with getBalance() — saves 1 API call).
+        const state = await this._hl._getSpotClearinghouseState({ fresh });
+        const balances = (state?.balances ?? []);
+        // Unified HL accounts: spot USDC IS the perp margin (§12.4 #8) — mark it shared.
+        // HIP-3 dex-scoped adapters report dex equity, which never contains spot USDC.
+        const unified = this._hl.isUnifiedAccount === true && this._hl.dex === "";
+        return balances.map((b) => ({
+            token: String(b.coin ?? ""),
+            total: String(b.total ?? "0"),
+            available: String(Number(b.total ?? 0) - Number(b.hold ?? 0)),
+            held: String(b.hold ?? "0"),
+            entryNtl: b.entryNtl !== undefined ? String(b.entryNtl) : undefined,
+            shared: unified && String(b.coin ?? "") === "USDC",
+        }));
+    }
+    async spotMarketOrder(symbol, side, size, opts) {
+        const what = `spot ${side} ${size} ${symbol}`;
+        // Pre-send (resolution, reference price): a failure is a definite "not placed".
+        let base;
+        let order;
+        let protection;
         try {
-            // Reuse cached spot clearinghouse state (shared with getBalance() — saves 1 API call)
-            const state = await this._hl._getSpotClearinghouseState();
-            const balances = (state?.balances ?? []);
-            return balances.map((b) => ({
-                token: String(b.coin ?? ""),
-                total: String(b.total ?? "0"),
-                available: String(Number(b.total ?? 0) - Number(b.hold ?? 0)),
-                held: String(b.hold ?? "0"),
-                entryNtl: b.entryNtl !== undefined ? String(b.entryNtl) : undefined,
-            }));
+            await this.init();
+            const resolved = this._resolveBase(symbol);
+            base = resolved.base;
+            // Reference = l2Book mid (the same single declared source as HL perps, §13.10 #5).
+            // Either side missing → PRICE_STALE (no one-sided "mid").
+            const book = await this.getSpotOrderbook(symbol);
+            const bestAsk = Number(book.asks[0]?.[0]);
+            const bestBid = Number(book.bids[0]?.[0]);
+            if (!(bestAsk > 0) || !(bestBid > 0) || !Number.isFinite(bestAsk) || !Number.isFinite(bestBid)) {
+                throw new PerpError("PRICE_STALE", `Hyperliquid spot ${base}: no two-sided l2Book to derive the mid reference price`, { exchange: "hyperliquid" });
+            }
+            const midPrice = (bestAsk + bestBid) / 2;
+            // Protection = mid ± the resolved slippage bound (design §13.2), aligned toward
+            // crossing on HL's spot grid (5 sig figs, max 8 − szDecimals decimals).
+            const isBuy = side === "buy";
+            const szDec = this.getSpotDecimals(base).size;
+            const { protectionPrice, appliedBps } = hlProtectionPrice(midPrice, side, opts.slippage.bps, szDec, 8);
+            await assertHlAppliedBps(appliedBps, `spot ${base} protection ${protectionPrice} vs reference ${midPrice}`);
+            protection = { referencePrice: String(midPrice), protectionPrice, appliedBps };
+            order = { assetIndex: 10000 + resolved.spotIndex, isBuy, price: protectionPrice, size: hlRoundSize(size, szDec) };
         }
-        catch {
-            return [];
+        catch (e) {
+            throw orderNotSent("hyperliquid", what, e);
+        }
+        // Send. A transport failure / unreadable body after the request may have placed
+        // the order → ORDER_PENDING. Any other error is the venue's explicit
+        // {"status":"err"} rejection or a signing failure before the request → definite.
+        let result;
+        try {
+            result = await this._rawPlaceSpotOrder({ ...order, orderType: { limit: { tif: "Ioc" } } });
         }
+        catch (e) {
+            if (isTransportFailure(e) || (e instanceof Error && e.message.startsWith("HL exchange API error ("))) {
+                throw orderOutcomeUnknown("hyperliquid", what, e);
+            }
+            if (e instanceof PerpError)
+                throw isDefiniteOrderFailure(e) ? e : orderOutcomeUnknown("hyperliquid", what, e);
+            throw new PerpError("ORDER_REJECTED", `hyperliquid ${what} rejected: ${e instanceof Error ? e.message : String(e)}`, { exchange: "hyperliquid" });
+        }
+        // Validate fill — HL returns status "ok" even for 0-fill IoC orders
+        this._validateOrderFill(result, base, side, order.size);
+        // The protection sent rides along (`protection`, read by the CLI's uniform spot output);
+        // `sentSize` = the size actually sent (floored to szDecimals).
+        return { ...result, protection, sentSize: order.size };
     }
-    async spotMarketOrder(symbol, side, size) {
+    /** Definite IOC outcome of a raw spot order response (same contract as HyperliquidAdapter.iocOutcomeOf). */
+    iocOutcomeOf(raw) {
+        return hlIocOutcome(raw);
+    }
+    async spotLimitOrder(symbol, side, price, size, opts) {
         await this.init();
         const { base, spotIndex } = this._resolveBase(symbol);
         const assetIndex = 10000 + spotIndex;
-        // Get mid price for slippage calculation
-        const book = await this.getSpotOrderbook(symbol);
-        const bestAsk = book.asks.length > 0 ? Number(book.asks[0][0]) : 0;
-        const bestBid = book.bids.length > 0 ? Number(book.bids[0][0]) : 0;
-        const midPrice = (bestAsk + bestBid) / 2;
-        if (midPrice <= 0)
-            throw new Error(`Cannot get price for spot ${base}`);
-        // 5% slippage for market orders
-        const slippage = 0.05;
-        const isBuy = side === "buy";
-        const slippagePrice = isBuy ? midPrice * (1 + slippage) : midPrice * (1 - slippage);
-        const dec = this._spotDecimals.get(base);
-        const szDec = dec?.size ?? 2;
-        const result = await this._rawPlaceSpotOrder({
-            assetIndex,
-            isBuy,
-            price: hlRoundPrice(slippagePrice, szDec),
-            size: hlRoundSize(Number(size), szDec),
-            orderType: { limit: { tif: "Ioc" } },
-        });
-        // Validate fill — HL returns status "ok" even for 0-fill IoC orders
-        this._validateOrderFill(result, base, side, size);
+        // TIF aliases (§13.3): GTC/IOC/ALO or native spellings; FOK → CAPABILITY_UNSUPPORTED.
+        const tif = hlTif(opts?.tif ?? "GTC");
+        const szDec = this.getSpotDecimals(base).size;
+        const what = `spot limit ${side} ${size} ${base} @ ${price}`;
+        // Pre-send: off-grid price → INVALID_TICK (refused, never rounded); size floored to the lot.
+        const sentPrice = hlRequirePriceOnGrid(price, szDec, 8, "spot limit price");
+        const sentSize = hlRoundSize(size, szDec);
+        // Same send contract as spotMarketOrder: a transport failure after the request may
+        // have placed the order → ORDER_PENDING; a {"status":"err"} body → definite rejection.
+        let result;
+        try {
+            result = await this._rawPlaceSpotOrder({
+                assetIndex,
+                isBuy: side === "buy",
+                price: sentPrice,
+                size: sentSize,
+                orderType: { limit: { tif } },
+            });
+        }
+        catch (e) {
+            if (isTransportFailure(e) || (e instanceof Error && e.message.startsWith("HL exchange API error ("))) {
+                throw orderOutcomeUnknown("hyperliquid", what, e);
+            }
+            if (e instanceof PerpError)
+                throw isDefiniteOrderFailure(e) ? e : orderOutcomeUnknown("hyperliquid", what, e);
+            throw new PerpError("ORDER_REJECTED", `hyperliquid ${what} rejected: ${e instanceof Error ? e.message : String(e)}`, { exchange: "hyperliquid" });
+        }
+        // Venue-final like perps: statuses[0] = resting {oid} (open) | filled {totalSz, avgPx, oid}
+        // | error (e.g. "Insufficient spot balance asset=10000") → ORDER_REJECTED, nothing placed.
+        // A missing status after an accepted request → EXCHANGE_ERROR (HyperliquidAdapter._validateVenueAck).
+        this._hl._validateVenueAck(result, what);
         return result;
     }
-    async spotLimitOrder(symbol, side, price, size, opts) {
+    /**
+     * Open spot orders (info `openOrders`, spot coins only: "@<spotIndex>" or "PURR/USDC").
+     * Symbols are "BASE/QUOTE" from spot meta; a coin missing from meta → EXCHANGE_ERROR (never guessed).
+     */
+    async getSpotOpenOrders(symbol) {
         await this.init();
-        const { base, spotIndex } = this._resolveBase(symbol);
-        const assetIndex = 10000 + spotIndex;
-        const rawTif = opts?.tif ?? "Gtc";
-        const tifMap = { IOC: "Ioc", GTC: "Gtc", ALO: "Alo" };
-        const tif = tifMap[rawTif.toUpperCase()] ?? rawTif;
-        const dec = this._spotDecimals.get(base);
-        const szDec = dec?.size ?? 2;
-        return this._rawPlaceSpotOrder({
-            assetIndex,
-            isBuy: side === "buy",
-            price: hlRoundPrice(Number(price), szDec),
-            size: hlRoundSize(Number(size), szDec),
-            orderType: { limit: { tif } },
-        });
+        const meta = this._cachedMetaCtx?.[0];
+        if (meta === undefined)
+            throw new PerpError("EXCHANGE_ERROR", "Hyperliquid spot meta not loaded", { exchange: "hyperliquid" });
+        const tokenName = new Map(meta.tokens.map(t => [t.index, t.name]));
+        const pairName = (spotIndex) => {
+            const u = meta.universe.find(x => x.index === spotIndex);
+            const b = u === undefined ? undefined : tokenName.get(u.tokens[0]);
+            const q = u === undefined ? undefined : tokenName.get(u.tokens[1]);
+            if (b === undefined || q === undefined)
+                throw new PerpError("EXCHANGE_ERROR", `Hyperliquid spot open order on unknown spot index ${spotIndex}`, { exchange: "hyperliquid" });
+            return `${b.toUpperCase()}/${q.toUpperCase()}`;
+        };
+        const rows = await this._infoPost({ type: "openOrders", user: this._hl.address });
+        if (!Array.isArray(rows))
+            throw new PerpError("EXCHANGE_ERROR", "Hyperliquid openOrders did not return an array", { exchange: "hyperliquid" });
+        const wantBase = symbol === null ? null : symbol.toUpperCase().split("/")[0];
+        const out = [];
+        for (const r of rows) {
+            const coin = String(r.coin ?? "");
+            let pair;
+            if (/^@\d+$/.test(coin))
+                pair = pairName(Number(coin.slice(1)));
+            else if (coin.includes("/"))
+                pair = coin.toUpperCase();
+            else
+                continue; // perp order
+            if (wantBase !== null && pair.split("/")[0] !== wantBase)
+                continue;
+            const orig = String(r.origSz ?? "");
+            const left = String(r.sz ?? "");
+            if (!/^\d+(\.\d+)?$/.test(orig) || !/^\d+(\.\d+)?$/.test(left)) {
+                throw new PerpError("EXCHANGE_ERROR", `Hyperliquid open order ${String(r.oid)}: unexpected size fields`, { exchange: "hyperliquid" });
+            }
+            const dec = Math.max((orig.split(".")[1] ?? "").length, (left.split(".")[1] ?? "").length);
+            out.push({
+                orderId: String(r.oid),
+                symbol: pair,
+                side: r.side === "B" ? "buy" : "sell",
+                price: String(r.limitPx),
+                size: orig,
+                filled: (Number(orig) - Number(left)).toFixed(dec),
+            });
+        }
+        return out;
     }
     async spotCancelOrder(symbol, orderId) {
         await this.init();
         const { spotIndex } = this._resolveBase(symbol);
         const assetIndex = 10000 + spotIndex;
+        const oid = Number(orderId);
+        if (!/^\d+$/.test(orderId) || !Number.isSafeInteger(oid)) {
+            throw new PerpError("INVALID_PARAMS", `Hyperliquid order id must be a decimal integer (got "${orderId}"); nothing was cancelled`, {
+                exchange: "hyperliquid", remediation: `Look up the order id: perp -e hyperliquid trade spot-orders ${symbol}`,
+            });
+        }
+        // statuses[0] "success" → cancelled; {error} → ORDER_REJECTED (trade.ts spotCancelResult).
         return this._signAndSendAction({
             type: "cancel",
-            cancels: [{ a: assetIndex, o: parseInt(orderId) }],
+            cancels: [{ a: assetIndex, o: oid }],
         });
     }
     /**
      * Transfer USDC between perp and spot accounts.
-     * HL uses separate balances — spot buys require USDC in the spot account.
-     * Uses SDK's transferBetweenSpotAndPerp (userSignedAction, not L1 action).
+     * HL uses separate balances (standard mode) — spot buys require USDC in the spot account.
      */
     async transferUsdcToSpot(amount) {
-        return this._hl.client.exchange.transferBetweenSpotAndPerp(amount, false);
+        return this._moveUsdc(String(amount), false);
     }
     async transferUsdcToPerp(amount) {
-        return this._hl.client.exchange.transferBetweenSpotAndPerp(amount, true);
+        return this._moveUsdc(String(amount), true);
+    }
+    /**
+     * Spot↔perp USDC move by the active signer tier: an agent signs the L1
+     * `agentSendAsset` (agents cannot sign user-signed actions); the master signs
+     * `usdClassTransfer`. No signer → NO_SIGNER_AVAILABLE from the adapter.
+     */
+    async _moveUsdc(amount, toPerp) {
+        // The master's usdClassTransfer moves USDC between spot and the NATIVE perp dex only. On a
+        // HIP-3 dex adapter it would fund the wrong dex, so it is refused (the agent's
+        // agentSendAsset names the dex explicitly).
+        if (this._hl.dex !== "" && this._hl.activeSignerTier !== "agent") {
+            throw new PerpError("NOT_IMPLEMENTED", `Hyperliquid spot↔perp transfer for HIP-3 dex "${this._hl.dex}" is not implemented for the master wallet (usdClassTransfer only funds the native perp dex)`, {
+                exchange: "hyperliquid",
+                remediation: `Use an agent wallet (perp wallet agent approve hyperliquid), or move the collateral to dex "${this._hl.dex}" in the Hyperliquid app`,
+            });
+        }
+        try {
+            return await (this._hl.activeSignerTier === "agent"
+                ? this._hl.agentSendAsset(amount, toPerp)
+                : this._hl.usdClassTransfer(amount, toPerp));
+        }
+        finally {
+            invalidateCache("acct"); // perp and spot balances both moved
+        }
+    }
+    /** SpotTransferCapable (§12.4 #4): USDC only; an `err` response is thrown, not returned. */
+    async transferToSpot(amount, asset) {
+        return this._checkedTransfer(amount, asset, false);
+    }
+    async transferToPerp(amount, asset) {
+        return this._checkedTransfer(amount, asset, true);
+    }
+    async _checkedTransfer(amount, asset, toPerp) {
+        if (asset !== "USDC") {
+            throw new PerpError("INVALID_PARAMS", `Hyperliquid spot↔perp transfer only moves USDC (got ${asset})`, { exchange: "hyperliquid" });
+        }
+        const n = Number(amount);
+        if (!Number.isFinite(n) || n <= 0)
+            throw new PerpError("INVALID_PARAMS", `Transfer amount must be positive (got ${amount})`);
+        const res = await this._moveUsdc(amount, toPerp);
+        if (res?.status === "err") {
+            throw new PerpError("EXCHANGE_ERROR", `Hyperliquid ${toPerp ? "spot→perp" : "perp→spot"} transfer rejected: ${String(res.response)}`, { exchange: "hyperliquid" });
+        }
+        return res;
     }
     /** Get the spot asset index (without the 10000 offset) */
     getSpotIndex(base) {
@@ -241,7 +417,10 @@ export class HyperliquidSpotAdapter {
         const dec = this._spotDecimals.get(base.toUpperCase());
         if (dec)
             return dec;
-        throw new Error(`No decimal info for spot token ${base}. Ensure init() completed successfully.`);
+        throw new PerpError("SYMBOL_NOT_FOUND", `Hyperliquid spot ${base.toUpperCase()}: no szDecimals in spot meta — refusing to size the order on a guess`, {
+            exchange: "hyperliquid",
+            remediation: "Retry (spot meta may not have loaded); if it persists the token is not tradeable via this CLI",
+        });
     }
     /**
      * Resolve a symbol to its actual spot base token and index.
@@ -282,16 +461,21 @@ export class HyperliquidSpotAdapter {
         const r = result;
         const statuses = r?.response?.data?.statuses;
         if (!statuses || statuses.length === 0) {
-            throw new Error(`Spot ${side} ${base}: no order status in response`);
+            // Accepted request without a per-order status: the outcome is unknown.
+            throw orderOutcomeUnknown("hyperliquid", `spot ${side} ${base}`, new Error("no order status in response"));
         }
         const st = statuses[0];
         if (st.error) {
-            throw new Error(`Spot ${side} ${base}: ${st.error}`);
+            throw new PerpError("ORDER_REJECTED", `Spot ${side} ${base}: ${st.error}`, { exchange: "hyperliquid" });
         }
         const filled = st.filled;
+        if (st.resting !== undefined) {
+            // An IoC never rests; a resting status means the order is live — do not resubmit.
+            throw orderOutcomeUnknown("hyperliquid", `spot ${side} ${base}`, new Error("IoC order reported resting"));
+        }
         if (!filled || Number(filled.totalSz ?? 0) === 0) {
-            // Resting or 0-fill → for IoC market orders this means no fill
-            throw new Error(`Spot ${side} ${base}: order not filled (0 of ${requestedSize} ${base}). Check price/liquidity.`);
+            // 0-fill IoC: cancelled by the venue, nothing filled (definite).
+            throw new PerpError("ORDER_REJECTED", `Spot ${side} ${base}: order not filled (0 of ${requestedSize} ${base}). Check price/liquidity.`, { exchange: "hyperliquid" });
         }
     }
     async _rawPlaceSpotOrder(opts) {
@@ -317,7 +501,14 @@ export class HyperliquidSpotAdapter {
         return this._signAndSendAction(action);
     }
     async _signAndSendAction(action) {
-        return this._hl.exchangeAction(action);
+        try {
+            return await this._hl.exchangeAction(action);
+        }
+        finally {
+            // Spot balances / open orders changed (or may have): later reads in this or another
+            // process (the acct: disk cache is shared) must not serve the pre-order snapshot.
+            invalidateCache("acct");
+        }
     }
     async _infoPost(body) {
         const baseUrl = this._hl.isTestnet