perp-cli 0.12.15 → 0.14.0

package/dist/exchanges/hyperliquid.js

@@ -1,19 +1,357 @@
-import { Hyperliquid } from "hyperliquid";
 import { LocalEvmSigner } from "../signer/index.js";
-import { PerpError } from "../errors.js";
+import { DEFINITE_ORDER_FAILURE_CODES, PerpError, classifyError, extractErrorMessage, orderNotSent, orderOutcomeUnknown, sendFailure } from "../errors.js";
+import { parseFiniteVenueNumber, venueRateField } from "../utils/numeric.js";
+import { alignProtectionPrice, floorSize, formatComputedPrice, slippagePrice } from "./precision.js";
+import { unsupported } from "./trading-v2.js";
+import { buildHlUserSignedAction, hlUserSignedNonceField, signHlL1Action, signHlUserSignedAction } from "./hl-signing.js";
+import { HL_CLOID_RE } from "./venues/hyperliquid.js";
+import { rateLimitedError } from "./rate-limiter.js";
+import { fetchAndCache, withCache, TTL_ACCOUNT } from "../cache.js";
+import { approvalFromMax, builderGateOf, hlFeeTenthsBps, NO_BUILDER, requireFeeBps } from "./builder-fee.js";
+/**
+ * Map a TIF input to HL's native value (design §13.3). Accepts the common names
+ * GTC/IOC/ALO and the native spellings case-insensitively. FOK is not offered by
+ * HL (no FOK emulation, §13.3) → CAPABILITY_UNSUPPORTED; anything else likewise.
+ */
+export function hlTif(raw) {
+    const t = raw.trim().toUpperCase();
+    if (t === "GTC")
+        return "Gtc";
+    if (t === "IOC")
+        return "Ioc";
+    if (t === "ALO")
+        return "Alo";
+    if (t === "FOK") {
+        throw unsupported("Hyperliquid", "fok", "Hyperliquid has no fill-or-kill time-in-force (partial IOC fills cannot be undone)", "Use --tif IOC (partial fills possible) or GTC");
+    }
+    throw unsupported("Hyperliquid", "timeInForce", `time-in-force ${raw} is not offered`, "Use one of: GTC, IOC, ALO");
+}
+/** HL lot step implied by szDecimals ("1" for 0, "0.001" for 3) — sizes are floored to it (floorSize). */
+export function hlSizeStep(szDecimals) {
+    return szDecimals <= 0 ? "1" : `0.${"0".repeat(szDecimals - 1)}1`;
+}
+/**
+ * Slippage-bounded IOC protection price (design §13.2, §13.10 #5).
+ *
+ * `reference` × (1 ± bps/10000), then aligned TOWARD CROSSING (buy → up, sell →
+ * down) on HL's price grid: at most 5 significant figures and at most
+ * `maxDecimals − szDecimals` decimals (maxDecimals 6 perps / 8 spot); integer
+ * prices are always valid. The returned `appliedBps` is the bound actually sent
+ * (after rounding) relative to the reference — it can exceed the requested bps
+ * by up to one grid step because alignment never narrows the bound toward
+ * not-crossing.
+ */
+export function hlProtectionPrice(reference, side, bps, szDecimals, maxDecimals) {
+    const raw = slippagePrice(String(reference), side, bps);
+    const px = Number(raw);
+    let e = Math.floor(Math.log10(px));
+    if (10 ** (e + 1) <= px)
+        e += 1;
+    if (10 ** e > px)
+        e -= 1;
+    const decimals = Math.max(0, Math.min(maxDecimals - szDecimals, 4 - e));
+    const tick = decimals === 0 ? "1" : `0.${"0".repeat(decimals - 1)}1`;
+    const protectionPrice = alignProtectionPrice(raw, tick, side);
+    const appliedBps = Math.abs(Number(protectionPrice) - reference) / reference * 10_000;
+    return { protectionPrice, appliedBps };
+}
+/**
+ * A USER-SUPPLIED limit / trigger / modify price checked against HL's price grid (design §10.10:
+ * an off-grid limit price is refused, never rounded — rounding to nearest can move a buy price UP).
+ * HL docs (trading/tick-and-lot-size): "Prices can have up to 5 significant figures, but no more
+ * than MAX_DECIMALS - szDecimals decimal places where MAX_DECIMALS is 6 for perps and 8 for spot.
+ * Integer prices are always allowed, regardless of the number of significant figures."
+ * Non-numeric / non-positive → INVALID_PARAMS; off-grid → INVALID_TICK (with the nearest on-grid
+ * prices below / above). Returns the price normalized (no leading / trailing zeros). Computed
+ * prices (protection, market-trigger `p`) are aligned with hlProtectionPrice instead.
+ */
+export function hlRequirePriceOnGrid(price, szDecimals, maxDecimals, what) {
+    const s = String(price).trim();
+    if (!/^\d+(\.\d+)?$/.test(s) || !(Number(s) > 0)) {
+        throw new PerpError("INVALID_PARAMS", `Hyperliquid ${what} must be a positive plain decimal (got "${price}")`, {
+            exchange: "hyperliquid", remediation: "Pass a plain decimal price such as 3012.5 (no exponent, sign or spaces)",
+        });
+    }
+    const [ipRaw, fpRaw = ""] = s.split(".");
+    const ip = ipRaw.replace(/^0+(?=\d)/, "");
+    const fp = fpRaw.replace(/0+$/, "");
+    const normalized = fp === "" ? ip : `${ip}.${fp}`;
+    if (fp === "")
+        return normalized; // integer prices are always valid
+    const maxDec = Math.max(0, maxDecimals - szDecimals);
+    const sigFigs = (ip + fp).replace(/^0+/, "").length;
+    if (fp.length <= maxDec && sigFigs <= 5)
+        return normalized;
+    // Nearest on-grid prices: the grid tick at this magnitude (≤ 5 sig figs, ≤ maxDec decimals).
+    const px = Number(normalized);
+    const e = Math.floor(Math.log10(px));
+    const decimals = Math.max(0, Math.min(maxDec, 4 - e));
+    const tick = decimals === 0 ? "1" : `0.${"0".repeat(decimals - 1)}1`;
+    const above = alignProtectionPrice(normalized, tick, "buy");
+    const below = px >= Number(tick) ? alignProtectionPrice(normalized, tick, "sell") : null;
+    throw new PerpError("INVALID_TICK", `Hyperliquid ${what} ${price} is off the price grid (max 5 significant figures and ${maxDec} decimals for szDecimals ${szDecimals}); nothing was sent`, {
+        exchange: "hyperliquid",
+        remediation: `Use an on-grid price, e.g. ${below !== null ? `${below} or ` : ""}${above}`,
+    });
+}
+export const HL_CCTP_ROUTES = {
+    // Forwarding fee: Circle documents 0.2 USDC for Arbitrum; other chains' fee is not published (null = unknown).
+    arbitrum: { cctpDomain: 3, forwardingFeeUsdc: "0.2" },
+    ethereum: { cctpDomain: 0, forwardingFeeUsdc: null },
+    base: { cctpDomain: 6, forwardingFeeUsdc: null },
+};
+/**
+ * A COMPUTED price (strategy quote, grid level, slice limit) moved onto the HL price grid in the
+ * passive direction: "down" for a buy, "up" for a sell — never more aggressive than computed.
+ * User-supplied prices are never aligned (hlRequirePriceOnGrid refuses them instead).
+ */
+export function hlAlignPriceToGrid(price, szDecimals, maxDecimals, direction) {
+    const s = String(price).trim();
+    if (!/^\d+(\.\d+)?$/.test(s) || !(Number(s) > 0)) {
+        throw new PerpError("INVALID_PARAMS", `Hyperliquid computed price must be a positive plain decimal (got "${price}")`, { exchange: "hyperliquid" });
+    }
+    const px = Number(s);
+    const maxDec = Math.max(0, maxDecimals - szDecimals);
+    const e = Math.floor(Math.log10(px));
+    // ≤ 5 significant figures at this magnitude, ≤ maxDec decimals; integers are always valid.
+    const decimals = Math.max(0, Math.min(maxDec, 4 - e));
+    const tick = decimals === 0 ? "1" : `0.${"0".repeat(decimals - 1)}1`;
+    const aligned = alignProtectionPrice(s, tick, direction === "up" ? "buy" : "sell");
+    if (!(Number(aligned) > 0)) {
+        throw new PerpError("INVALID_TICK", `Hyperliquid computed price ${price} aligns to 0 on the grid`, { exchange: "hyperliquid" });
+    }
+    // Aligning up across a power of ten (e.g. 9.99995 → 10.0000) stays valid: hlRequirePriceOnGrid re-checks.
+    return hlRequirePriceOnGrid(aligned, szDecimals, maxDecimals, "computed price");
+}
+/**
+ * Grid rounding (toward crossing) can widen the bound past the requested bps; a bound
+ * actually sent above the venue's maxSlippageBps → INVALID_PARAMS before anything is sent.
+ * (slippage.js is imported lazily: it loads settings and the venue registry.)
+ */
+export async function assertHlAppliedBps(appliedBps, what) {
+    const { venueMaxSlippageBps } = await import("./slippage.js");
+    const max = venueMaxSlippageBps("hyperliquid");
+    if (!(appliedBps <= max)) {
+        throw new PerpError("INVALID_PARAMS", `Hyperliquid ${what}: the bound after HL price-grid rounding is ${appliedBps.toFixed(2)} bps, above the venue maximum ${max} bps`, {
+            exchange: "hyperliquid",
+            remediation: "Lower --slippage-bps, or place a limit order",
+        });
+    }
+}
+/**
+ * Definite IOC outcome of a raw HL `order` response (shared contract with the
+ * perp-order lane, design §13.10 #4). Reads `response.data.statuses[0]`:
+ * - `{ filled: { totalSz } }` with a plain decimal totalSz → that size, final;
+ * - `{ error }` that is HL's IOC no-match cancel ("could not immediately match")
+ *   → the venue explicitly cancelled the IOC with nothing filled → "0", final;
+ * - anything else (resting, other errors, unexpected shape) → null: the shape
+ *   does not prove a final fill size.
+ */
+export function hlIocOutcome(raw) {
+    const statuses = raw?.response?.data?.statuses;
+    if (!Array.isArray(statuses) || statuses.length === 0)
+        return null;
+    const st = statuses[0];
+    if (!st || typeof st !== "object")
+        return null;
+    const filled = st.filled;
+    if (filled && typeof filled === "object") {
+        return typeof filled.totalSz === "string" && /^\d+(\.\d+)?$/.test(filled.totalSz)
+            ? { filledSize: filled.totalSz, final: true }
+            : null;
+    }
+    if (st.resting === undefined && typeof st.error === "string" && /could not immediately match/i.test(st.error)) {
+        return { filledSize: "0", final: true };
+    }
+    return null;
+}
+/**
+ * Decimal amount string for HL actions ("12.50" → "12.5"). Non-positive / non-numeric → INVALID_PARAMS
+ * (nothing is rounded or substituted).
+ */
+export function hlAmountString(amount) {
+    const a = amount.trim();
+    if (!/^\d+(\.\d+)?$/.test(a) || !(Number(a) > 0)) {
+        throw new PerpError("INVALID_PARAMS", `Hyperliquid amount must be a positive decimal (got "${amount}")`, { exchange: "hyperliquid" });
+    }
+    const noLead = a.replace(/^0+(?=\d)/, "");
+    return noLead.includes(".") ? noLead.replace(/\.?0+$/, "") : noLead;
+}
+/**
+ * Verdict of a twapOrder / twapCancel response. The envelope is "ok" even when the TWAP was
+ * refused: the verdict is `response.data.status` — `{ running: { twapId } }` (placed), the string
+ * "success" (cancelled) or `{ error }` (refused → ORDER_REJECTED). Any other shape → ORDER_PENDING.
+ */
+export function hlValidateTwapResult(result, what) {
+    const status = result?.response?.data?.status;
+    if (status === "success")
+        return;
+    if (status !== null && typeof status === "object") {
+        const st = status;
+        if (typeof st.error === "string" && st.error !== "") {
+            throw new PerpError("ORDER_REJECTED", `Hyperliquid ${what} rejected: ${st.error}`, { exchange: "hyperliquid" });
+        }
+        if (st.running !== null && typeof st.running === "object" && typeof st.running.twapId === "number")
+            return;
+    }
+    throw orderOutcomeUnknown("hyperliquid", what, new Error(`unexpected TWAP response ${JSON.stringify(result).slice(0, 200)}`), "Do NOT resubmit — check the account's TWAP orders on Hyperliquid first");
+}
+/** HL TWAP running time bounds in minutes: "from 5 minutes to 7 days" (docs trading/order-types, TWAP details). */
+export const HL_TWAP_MIN_MINUTES = 5;
+export const HL_TWAP_MAX_MINUTES = 7 * 24 * 60;
+/** HL TWAP "$100 minimum total order size" (same page). */
+export const HL_TWAP_MIN_NOTIONAL_USD = 100;
+/**
+ * Pre-check of a native TWAP against the venue's documented bounds — docs trading/order-types:
+ * "Running time can be set from 5 minutes to 7 days, with a $100 minimum total order size."
+ * The total order size is valued at the mark price. Nothing is sent when it throws.
+ */
+export function hlAssertTwapBounds(symbol, size, durationMinutes, markPrice) {
+    if (!Number.isInteger(durationMinutes) || durationMinutes < HL_TWAP_MIN_MINUTES || durationMinutes > HL_TWAP_MAX_MINUTES) {
+        throw new PerpError("INVALID_PARAMS", `Hyperliquid TWAP running time must be a whole number of minutes from ${HL_TWAP_MIN_MINUTES} to ${HL_TWAP_MAX_MINUTES} (7 days); got ${durationMinutes}`, {
+            exchange: "hyperliquid", remediation: `Pass a duration between ${HL_TWAP_MIN_MINUTES} and ${HL_TWAP_MAX_MINUTES} minutes`,
+        });
+    }
+    const sz = Number(size);
+    if (!(sz > 0) || !Number.isFinite(sz)) {
+        throw new PerpError("INVALID_PARAMS", `Hyperliquid TWAP size must be a positive number (got "${size}")`, { exchange: "hyperliquid" });
+    }
+    const notional = sz * markPrice;
+    if (notional < HL_TWAP_MIN_NOTIONAL_USD) {
+        throw new PerpError("SIZE_TOO_SMALL", `Hyperliquid TWAP total order size must be at least $${HL_TWAP_MIN_NOTIONAL_USD}; ${size} ${symbol.toUpperCase()} is ~$${notional.toFixed(2)} at mark ${markPrice}`, {
+            exchange: "hyperliquid", remediation: `Raise the size to at least $${HL_TWAP_MIN_NOTIONAL_USD} notional, or place a regular order`,
+        });
+    }
+}
+/**
+ * "sl" when the trigger is on the adverse side of the reference (buy ≥ ref, sell ≤ ref), else "tp".
+ * The reference must be the MARK price — docs trading/take-profit-and-stop-loss-orders-tp-sl:
+ * "The mark price is used to trigger TP/SL orders."
+ */
+export function hlTriggerKind(side, trigger, reference) {
+    return (side === "buy" ? trigger >= reference : trigger <= reference) ? "sl" : "tp";
+}
+/** HL spot coin names: "@<pair index>" or "<BASE>/<QUOTE>" (e.g. "@107", "PURR/USDC"). Perp coins are neither. */
+/** Markets without a position whose setting `account settings` reads (recent fills, activeAssetData weight 20 each). */
+export const HL_SETTINGS_FILL_MARKETS = 5;
+export function hlIsSpotCoin(coin) {
+    return coin.startsWith("@") || coin.includes("/");
+}
+/**
+ * Destination of a withdraw3 / usdSend: a 20-byte hex address, sent lower-cased (the venue
+ * hashes the string as signed; the official SDKs send lower-case). Anything else → INVALID_PARAMS.
+ */
+export function hlDestination(destination) {
+    const d = String(destination).trim();
+    if (!/^0x[0-9a-fA-F]{40}$/.test(d) || /^0x0{40}$/.test(d)) {
+        throw new PerpError("INVALID_PARAMS", `Hyperliquid destination must be a 0x-prefixed 20-byte address (got "${destination}"); nothing was sent`, { exchange: "hyperliquid" });
+    }
+    return d.toLowerCase();
+}
+/**
+ * On-disk lifetime of the public market metadata (info `meta`, `perpDexs`) shared by every CLI
+ * process (cache.ts). Asset ids are universe positions; a market listed inside this window is
+ * unknown (SYMBOL_NOT_FOUND) until the entry expires.
+ */
+export const HL_MARKET_META_TTL_MS = 5 * 60_000;
+/**
+ * On-disk lifetime of the user's account abstraction mode (info `userAbstraction`), shared by
+ * every CLI process of the same network + address. Docs ("Rate limits and user limits"): "REST
+ * requests share an aggregated weight limit of 1200 per minute" and `userAbstraction` is one of
+ * "All other documented `info` requests [that] have weight 20" — read on every invocation it was
+ * the largest fixed cost of a command. The mode is a per-user setting that only changes by an
+ * explicit `userSetAbstraction`; `perp wallet manage account-mode` drops the entry when it sets
+ * one and always reads it fresh. A change made outside this CLI (web app) is seen after at most
+ * this window. The key is outside the `acct:` prefix, so the per-command account-cache
+ * invalidation does not force a re-read.
+ */
+export const HL_ABSTRACTION_TTL_MS = 60_000;
+/** Cache-key prefix of the abstraction mode for a network (invalidateCache prefix: every address). */
+export function hlAbstractionCachePrefix(network) {
+    return `mode:hl:${network}:abstraction:`;
+}
+/** Venue margin restriction of a universe entry: strictIsolated (no margin removal) / noCross; null = unrestricted. */
+export function hlMarginModeOf(asset) {
+    if (asset.marginMode === "strictIsolated")
+        return "strictIsolated";
+    if (asset.marginMode === "noCross" || asset.onlyIsolated === true)
+        return "noCross";
+    return null;
+}
+/** HIP-3 (builder-deployed) asset ids start at 110000 (110000 + dexIndex × 10000 + universe index). */
+export const HIP3_MIN_ASSET_ID = 110_000;
+/**
+ * HL's documented slippage tolerance for MARKET TP/SL triggers ("TP/SL market orders have a
+ * slippage tolerance of 10%", docs trading/take-profit-and-stop-loss-orders-tp-sl). A market
+ * trigger's `p` is sent at trigger ± this bound (the official SDK / app send a wide limit, never
+ * the trigger itself): if the venue honours `p` as a limit, a `p` equal to the trigger could
+ * rest unfilled once the stop fires.
+ */
+export const HL_MARKET_TPSL_SLIPPAGE_BPS = 1000;
+/** A `{"status":"err","response":…}` envelope from POST /exchange: the venue processed the request and refused it. */
+export class HlErrResponse extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "HlErrResponse";
+    }
+}
+/**
+ * A user-signed action (withdraw3 / usdSend / usdClassTransfer / approveBuilderFee / tokenDelegate)
+ * the venue answered with an `err` envelope executed nothing (live testnet 2026-10-02:
+ * withdraw3 → {"status":"err","response":"Error withdrawing from bridge"}, ledger and balance
+ * unchanged). A balance / margin refusal keeps its code (INSUFFICIENT_BALANCE — callers size from
+ * it); any other refusal → ACTION_REJECTED (definite, non-retryable). Transport / parse failures
+ * (no envelope) are returned unchanged — their outcome is unknown.
+ */
+export function hlUserActionRejection(type, e) {
+    if (!(e instanceof HlErrResponse))
+        return e;
+    const c = classifyError(e);
+    if (c.code === "INSUFFICIENT_BALANCE" || c.code === "MARGIN_INSUFFICIENT") {
+        return new PerpError(c.code, e.message, { exchange: "hyperliquid", action: type });
+    }
+    return new PerpError("ACTION_REJECTED", `Hyperliquid refused ${type}: ${e.message} — nothing was executed`, {
+        exchange: "hyperliquid", action: type, venueResponse: e.message,
+        remediation: "The venue refused the request and moved nothing; check the venue message above (balances: perp -e hyperliquid portfolio)",
+    });
+}
+/** L1 action types that place or amend orders (their refusal is ORDER_REJECTED; every other type → ACTION_REJECTED). */
+const HL_ORDER_ACTION_TYPES = new Set(["order", "batchModify", "modify", "twapOrder"]);
+/**
+ * An L1 action (order / cancel / updateLeverage / agentSendAsset / …) answered with a top-level
+ * `err` envelope was refused as a whole and executed nothing — docs for-developers/api/error-responses:
+ * "Some errors are a deterministic function of the payload itself, and these are instead returned
+ * earlier as part of pre-validation. In this case only one error is returned for the entire payload".
+ * A balance / margin refusal keeps its code; any other refusal → ORDER_REJECTED (order actions) or
+ * ACTION_REJECTED — definite and non-retryable, never the retryable EXCHANGE_ERROR. Transport /
+ * parse failures (no envelope) are returned unchanged.
+ */
+export function hlL1ActionRejection(type, e) {
+    if (!(e instanceof HlErrResponse))
+        return e;
+    const c = classifyError(e);
+    if (c.code === "INSUFFICIENT_BALANCE" || c.code === "MARGIN_INSUFFICIENT") {
+        return new PerpError(c.code, e.message, { exchange: "hyperliquid", action: type });
+    }
+    const isOrder = HL_ORDER_ACTION_TYPES.has(type);
+    return new PerpError(isOrder ? "ORDER_REJECTED" : "ACTION_REJECTED", `Hyperliquid refused ${type}: ${e.message} — nothing was executed`, {
+        exchange: "hyperliquid", action: type, venueResponse: e.message,
+        remediation: "The venue refused the whole request and executed nothing; fix the cause named in the venue message above before sending it again",
+    });
+}
 export class HyperliquidAdapter {
     name = "hyperliquid";
     chain = "evm";
     aliases = ["hl"];
     /**
-     * Reflects whether perp + spot share the same USDC pool (true for unified /
-     * portfolio mode) or are separately margined (false for standard mode and
-     * HIP-3 dex accounts). Populated during init() from _getAbstractionMode();
+     * Reflects whether perp + spot share the same collateral pool (true for unified /
+     * portfolio mode — a per-user setting, HIP-3 dexes included) or are separately
+     * margined (false for standard / unset "default"). Populated during init() from _getAbstractionMode()
+     * (disk-cached for HL_ABSTRACTION_TTL_MS, so init reads the venue at most once per window);
      * defaults to false until init resolves so callers never assume unified
      * semantics for accounts that have never opted in. Codex v0.12.12 final QA #1.
      */
     isUnifiedAccount = false;
-    sdk;
     _address;
     _privateKey;
     _testnet;
@@ -24,22 +362,23 @@ export class HyperliquidAdapter {
     _assetMap = new Map();
     _assetMapReverse = new Map();
     _szDecimalsMap = new Map(); // symbol → szDecimals
+    /** symbol → venue marginMode restriction (meta universe `marginMode` / `onlyIsolated`); absent = none. */
+    _marginModeMap = new Map();
     /** HIP-3 deployed perp dex name. Empty string = native (validator) perps. */
     _dex = "";
+    /** Why the last asset-map load refused to map the dex (unknown dex / asset id below the HIP-3 range). */
+    _assetMapError = null;
     static _lastNonce = 0;
     _marketsCache = null;
     _marketsCacheTime = 0;
     static CACHE_TTL = 30_000;
+    /**
+     * Builder-fee gate (settings builder.hyperliquid + confirmed master approval); null = not
+     * configured. Set by createHyperliquid — the adapter never reads settings.
+     */
+    builderFee = null;
     constructor(privateKey, testnet = false) {
-        // Disable WebSocket in SDK — we use REST for all info calls and raw
-        // fetch for /exchange. This avoids the false "Please install ws" warning
-        // caused by the SDK's require('ws') failing in ESM context.
-        this.sdk = new Hyperliquid({
-            privateKey,
-            testnet,
-            walletAddress: undefined,
-            enableWs: false,
-        });
+        // No SDK: /info reads go through _infoPost, /exchange actions are signed here (hl-signing.ts).
         this._address = "";
         this._privateKey = privateKey ?? "";
         this._testnet = testnet;
@@ -54,12 +393,44 @@ export class HyperliquidAdapter {
     get dex() {
         return this._dex;
     }
-    get client() {
-        return this.sdk;
-    }
     get address() {
         return this._address;
     }
+    /**
+     * Builder decision for an order on `assetIndex` (null = adapter-level, e.g. dry-run).
+     * HIP-3 (this adapter's dex, or a builder-deployed asset id ≥ 100000) never carries it.
+     */
+    async builderDecision(assetIndex) {
+        const gate = builderGateOf(this);
+        if (gate === null)
+            return NO_BUILDER;
+        const hip3 = this._dex !== "" || (assetIndex !== null && assetIndex >= 100_000);
+        return gate.decide({ hip3 });
+    }
+    /**
+     * HL `order` action. `builder: { b, f }` (f = tenths of a bp, builder-codes docs) is appended
+     * only when the gate approves it — key order type, orders, grouping, builder (msgpack hash).
+     */
+    async _orderAction(orders, grouping, assetIndex) {
+        const action = { type: "order", orders, grouping };
+        const d = await this.builderDecision(assetIndex);
+        if (d.applied !== null)
+            action.builder = { b: d.applied.identity.toLowerCase(), f: hlFeeTenthsBps(requireFeeBps(d.applied)) };
+        return action;
+    }
+    /**
+     * Master approval for `target` (info maxBuilderFee: the approved ceiling in tenths of a bp,
+     * 0 = none). Read for this adapter's account address (the master — agents cannot approve).
+     */
+    async builderApprovalOf(target) {
+        if (!this._address)
+            return { status: "unknown", reason: "no account address loaded" };
+        const max = await this._infoPost({ type: "maxBuilderFee", user: this._address, builder: target.identity });
+        if (typeof max !== "number" || !Number.isFinite(max) || max < 0) {
+            return { status: "unknown", reason: `unexpected maxBuilderFee response ${JSON.stringify(max).slice(0, 120)}` };
+        }
+        return approvalFromMax(max === 0 ? null : max / 10, requireFeeBps(target));
+    }
     get isTestnet() {
         return this._testnet;
     }
@@ -100,22 +471,17 @@ export class HyperliquidAdapter {
     }
     /** Resolve the active signer across three tiers. */
     _resolveSigner() {
-        // Tier 1: agent (when registered, not expired, --no-agent NOT set)
+        // Tier 1: agent (when registered, --no-agent NOT set). An expired agent record is an
+        // explicit error — never a silent switch to the master signer; --no-agent is the opt-in.
         if (!this._useNoAgent && this._agentSigner && this._agentMeta) {
             const expiresAt = new Date(this._agentMeta.expiresAt).getTime();
-            const expired = expiresAt < Date.now();
-            if (expired) {
-                // Skip Tier 1 only if Tier 2/3 available; otherwise throw AGENT_EXPIRED
-                if (!this._evmSigner && !this._privateKey) {
-                    throw new PerpError("AGENT_EXPIRED", "Agent wallet has expired", {
-                        remediation: "perp wallet agent approve hyperliquid --rotate",
-                    });
-                }
-                // fall through to Tier 2/3
-            }
-            else {
-                return { tier: "agent", signer: this._agentSigner };
+            if (expiresAt < Date.now()) {
+                throw new PerpError("AGENT_EXPIRED", `Hyperliquid agent wallet ${this._agentMeta.agentEvmAddress} expired at ${this._agentMeta.expiresAt}`, {
+                    exchange: "hyperliquid",
+                    remediation: "Re-approve the agent: perp wallet agent approve hyperliquid — or sign with the master wallet for this command: --no-agent",
+                });
             }
+            return { tier: "agent", signer: this._agentSigner };
         }
         // Tier 2: OWS master (_evmSigner set via setSigner)
         if (this._evmSigner) {
@@ -135,15 +501,6 @@ export class HyperliquidAdapter {
         });
     }
     async init() {
-        // Suppress "WebSocket connected" noise from hyperliquid SDK
-        const origLog = console.log;
-        console.log = () => { };
-        try {
-            await this.sdk.connect();
-        }
-        finally {
-            console.log = origLog;
-        }
         // Initialize EVM signer if not externally injected (skip if no key — read-only mode)
         if (!this._evmSigner && this._privateKey) {
             this._evmSigner = await LocalEvmSigner.create(this._privateKey);
@@ -155,31 +512,41 @@ export class HyperliquidAdapter {
         // Build asset index map
         await this._loadAssetMap();
         // Resolve abstraction mode → isUnifiedAccount flag for callers
-        // (portfolio accounting + spot-perp arb sizing). Standard/HIP-3 dex
-        // accounts are NOT unified (perp + spot are separately margined).
+        // (portfolio accounting + spot-perp arb sizing). The mode is per user;
+        // standard / "default" accounts are NOT unified.
         // Read-only paths (no address yet) can't query userAbstraction; leave the
         // default false until a downstream caller invokes setAddress + the cache
         // populates during getBalance(). Codex v0.12.12 final QA #1.
+        // A failed userAbstraction read propagates: a silently-kept `false` would mis-size
+        // every caller that branches on the account mode.
         if (this._address) {
-            try {
-                const mode = await this._getAbstractionMode();
-                this.isUnifiedAccount = mode === "unified" || mode === "portfolio";
-            }
-            catch {
-                // If userAbstraction lookup fails, retain conservative default
-                // (false). getBalance() will surface the underlying error when called.
-            }
+            const mode = await this._getAbstractionMode();
+            // dexAbstraction is not unified (USDC stays in the perp balance).
+            this.isUnifiedAccount = mode === "unified" || mode === "portfolio";
         }
     }
+    /**
+     * info `meta` of this adapter's perp dex (universe: names, szDecimals, margin restrictions;
+     * collateralToken) — public static metadata, shared on disk by every CLI process for
+     * HL_MARKET_META_TTL_MS. Docs ("Rate limits and user limits"): "REST requests share an
+     * aggregated weight limit of 1200 per minute" and `meta` is one of "All other documented `info`
+     * requests [that] have weight 20" — re-reading it on every invocation (twice on a balance read)
+     * was most of a command's weight. Account state is never cached here.
+     */
+    _metaCached() {
+        return withCache(`mkt:hl:${this._network}:meta:${this._dex}`, HL_MARKET_META_TTL_MS, () => this._infoPost(this._dex ? { type: "meta", dex: this._dex } : { type: "meta" }));
+    }
     /** Load asset index map — supports native and HIP-3 dex. */
     async _loadAssetMap() {
+        this._assetMapError = null;
         try {
             if (this._dex) {
                 // HIP-3 deployed dex: asset indices use global offset scheme
                 // offset = 110000 + dexListIndex * 10000 (per Python SDK convention)
                 const [meta, dexList] = await Promise.all([
-                    this._infoPost({ type: "meta", dex: this._dex }),
-                    this._infoPost({ type: "perpDexs" }),
+                    this._metaCached(),
+                    // The dex list (weight 20) is public static metadata too; cached like `meta`.
+                    withCache(`mkt:hl:${this._network}:perpDexs`, HL_MARKET_META_TTL_MS, () => this._infoPost({ type: "perpDexs" })),
                 ]);
                 // Find this dex's position in the list (index 0 is native/null)
                 let dexOffset = 0;
@@ -190,11 +557,17 @@ export class HyperliquidAdapter {
                     }
                 }
                 if (dexOffset === 0) {
-                    console.error(`[hyperliquid] Dex "${this._dex}" not found in perpDexs list`);
+                    // Fail closed: offset 0 would map every HIP-3 coin onto a NATIVE asset id.
+                    throw new PerpError("SYMBOL_NOT_FOUND", `Hyperliquid perp dex "${this._dex}" is not in the venue's perpDexs list; no asset ids loaded`, {
+                        exchange: "hyperliquid", remediation: "Check the dex name: perp -e hyperliquid market dexes",
+                    });
                 }
                 if (meta?.universe) {
                     meta.universe.forEach((asset, idx) => {
                         const globalIdx = dexOffset + idx;
+                        if (!(globalIdx >= HIP3_MIN_ASSET_ID)) {
+                            throw new PerpError("SYMBOL_NOT_FOUND", `Hyperliquid dex "${this._dex}" asset ${asset.name} resolved to asset id ${globalIdx} (< ${HIP3_MIN_ASSET_ID}); refusing to load`, { exchange: "hyperliquid" });
+                        }
                         // Store both with and without dex prefix for flexible lookup
                         // API returns "km:GOOGL" but callers may use "GOOGL" or "KM:GOOGL"
                         const fullName = asset.name; // e.g., "km:GOOGL"
@@ -207,24 +580,44 @@ export class HyperliquidAdapter {
                             this._szDecimalsMap.set(fullName, asset.szDecimals);
                             this._szDecimalsMap.set(baseName, asset.szDecimals);
                         }
+                        const mm = hlMarginModeOf(asset);
+                        if (mm !== null) {
+                            this._marginModeMap.set(fullName, mm);
+                            this._marginModeMap.set(baseName, mm);
+                        }
                     });
                 }
             }
             else {
-                const meta = await this.sdk.info.perpetuals.getMeta();
+                // Native perps keep the "<COIN>-PERP" display names the former SDK symbol
+                // conversion produced (market list, positions, orders); _venueCoin() maps back.
+                const meta = await this._metaCached();
                 if (meta && meta.universe) {
                     meta.universe.forEach((asset, idx) => {
-                        this._assetMap.set(asset.name, idx);
-                        this._assetMapReverse.set(idx, asset.name);
+                        const sym = `${asset.name}-PERP`;
+                        this._assetMap.set(sym, idx);
+                        this._assetMapReverse.set(idx, sym);
                         if (asset.szDecimals !== undefined) {
-                            this._szDecimalsMap.set(asset.name, asset.szDecimals);
+                            this._szDecimalsMap.set(sym, asset.szDecimals);
                         }
+                        const mm = hlMarginModeOf(asset);
+                        if (mm !== null)
+                            this._marginModeMap.set(sym, mm);
                     });
                 }
             }
         }
         catch (e) {
-            console.error("[hyperliquid] Failed to load asset map:", e instanceof Error ? e.message : e);
+            // A HIP-3 map that cannot be proven correct is never left half-loaded.
+            if (this._dex) {
+                this._assetMap.clear();
+                this._assetMapReverse.clear();
+            }
+            // Kept and re-thrown at the point of use (getAssetIndex, getSzDecimals): a failed metadata
+            // read (429, transport) must surface as itself, never as "Unknown asset" / "not loaded" for
+            // every symbol. Commands that need no market metadata are not failed by it and print nothing.
+            this._assetMapError = e instanceof PerpError ? e
+                : new PerpError("EXCHANGE_ERROR", `Hyperliquid market metadata could not be loaded: ${e instanceof Error ? e.message : String(e)}`, { exchange: "hyperliquid" });
         }
     }
     /**
@@ -233,57 +626,90 @@ export class HyperliquidAdapter {
      */
     resolveSymbol(symbol) {
         const sym = symbol.toUpperCase();
-        if (this._assetMap.has(sym))
-            return sym;
-        if (this._assetMap.has(`${sym}-PERP`))
-            return `${sym}-PERP`;
-        if (sym.endsWith("-PERP") && this._assetMap.has(sym.replace(/-PERP$/, "")))
-            return sym.replace(/-PERP$/, "");
         if (sym.includes(":")) {
+            // A dex-prefixed symbol must name THIS adapter's dex — never rewritten onto another dex.
             const [prefix, base] = sym.split(":");
+            if (prefix.toLowerCase() !== this._dex.toLowerCase()) {
+                throw new PerpError("SYMBOL_NOT_FOUND", `Hyperliquid symbol ${symbol} is on dex "${prefix.toLowerCase()}", not ${this._dex ? `this adapter's dex "${this._dex}"` : "the native perp dex"}`, {
+                    exchange: "hyperliquid", remediation: `Select the dex: perp -e hyperliquid --dex ${prefix.toLowerCase()} ...`,
+                });
+            }
             const lower = `${prefix.toLowerCase()}:${base}`;
             if (this._assetMap.has(lower))
                 return lower;
             if (this._assetMap.has(base))
                 return base;
+            return this._caseInsensitive(sym) ?? sym;
+        }
+        if (this._assetMap.has(sym))
+            return sym;
+        if (this._assetMap.has(`${sym}-PERP`))
+            return `${sym}-PERP`;
+        if (sym.endsWith("-PERP") && this._assetMap.has(sym.replace(/-PERP$/, "")))
+            return sym.replace(/-PERP$/, "");
+        // Coins whose venue name is not upper-case (kPEPE, kSHIB, …): match the map case-insensitively.
+        return this._caseInsensitive(sym) ?? this._caseInsensitive(`${sym}-PERP`) ?? this._caseInsensitive(sym.replace(/-PERP$/, "")) ?? sym; // unknown → as-is, downstream SYMBOL_NOT_FOUND
+    }
+    /** The asset-map key equal to `upper` ignoring case, when exactly one exists (kPEPE-PERP for KPEPE-PERP). */
+    _caseInsensitive(upper) {
+        let hit = null;
+        for (const k of this._assetMap.keys()) {
+            if (k.toUpperCase() !== upper)
+                continue;
+            if (hit !== null && hit !== k)
+                return null;
+            hit = k;
         }
-        return sym; // return as-is, let downstream error
+        return hit;
     }
-    /** Get szDecimals for a symbol (cached from init/getMeta) */
+    /**
+     * szDecimals for a symbol (cached from init/getMeta). Rule #2: never assumed —
+     * meta not loaded → PRICE_STALE (retryable); loaded but no entry → SYMBOL_NOT_FOUND.
+     */
     getSzDecimals(symbol) {
         const resolved = this.resolveSymbol(symbol.toUpperCase());
         const dec = this._szDecimalsMap.get(resolved);
         if (dec !== undefined)
             return dec;
-        // Retry asset map load if empty
+        if (this._assetMapError)
+            throw this._assetMapError;
         if (this._szDecimalsMap.size === 0) {
-            console.error(`[hyperliquid] szDecimals not loaded for ${symbol}, using fallback 2`);
+            throw new PerpError("PRICE_STALE", `Hyperliquid market metadata (szDecimals) not loaded for ${symbol.toUpperCase()}`, {
+                exchange: "hyperliquid",
+                remediation: "Retry shortly — the meta request may have failed",
+            });
         }
-        return 2;
+        throw new PerpError("SYMBOL_NOT_FOUND", `Hyperliquid ${symbol.toUpperCase()}: no szDecimals in market metadata`, {
+            exchange: "hyperliquid",
+            remediation: "Check the symbol: perp market list -e hyperliquid",
+        });
     }
-    /** HL official price rounding: 5 significant figures */
-    _hlRoundPrice(px, szDecimals, maxDecimals = 6) {
-        if (px > 100_000)
-            return String(Math.round(px));
-        const sig5 = Number(px.toPrecision(5));
-        const priceDec = Math.max(0, maxDecimals - szDecimals);
-        return Number(sig5.toFixed(priceDec)).toString();
+    /** Lot step of a market from the loaded `meta` szDecimals (precision.lotStepOf) — no metaAndAssetCtxs / allMids read per order. */
+    lotStepOf(symbol) {
+        return hlSizeStep(this.getSzDecimals(symbol));
     }
     async getAssetIndex(symbol) {
         // Retry once if asset map is empty (e.g. init failed silently)
         if (this._assetMap.size === 0) {
             await this._loadAssetMap();
         }
+        if (this._assetMapError)
+            throw this._assetMapError;
         const resolved = this.resolveSymbol(symbol);
         const idx = this._assetMap.get(resolved);
-        if (idx !== undefined)
+        if (idx !== undefined) {
+            if (this._dex && !(idx >= HIP3_MIN_ASSET_ID)) {
+                throw new PerpError("SYMBOL_NOT_FOUND", `Hyperliquid dex "${this._dex}" asset ${symbol} has asset id ${idx} (< ${HIP3_MIN_ASSET_ID}); refusing to trade a native asset id`, { exchange: "hyperliquid" });
+            }
             return idx;
-        throw new Error(`Unknown asset: ${symbol}`);
+        }
+        throw new PerpError("SYMBOL_NOT_FOUND", `Unknown asset: ${symbol}`, { exchange: "hyperliquid" });
     }
     async getMarkets() {
         if (this._marketsCache && Date.now() - this._marketsCacheTime < HyperliquidAdapter.CACHE_TTL)
             return this._marketsCache;
         let universe;
+        let marginTables;
         let ctxs;
         let mids = {};
         if (this._dex) {
@@ -291,15 +717,42 @@ export class HyperliquidAdapter {
             const meta = await this._infoPost({ type: "metaAndAssetCtxs", dex: this._dex });
             universe = meta[0]?.universe ?? [];
             ctxs = meta[1] ?? [];
+            marginTables = meta[0]?.marginTables;
         }
         else {
             const [meta, allMids] = await Promise.all([
-                this.sdk.info.perpetuals.getMetaAndAssetCtxs(),
-                this.sdk.info.getAllMids(),
+                this._infoPost({ type: "metaAndAssetCtxs" }),
+                this._infoPost({ type: "allMids" }),
             ]);
-            universe = meta[0]?.universe ?? [];
+            // Native perps: "<COIN>-PERP" display names (see _loadAssetMap); allMids is keyed by the raw coin.
+            universe = (meta[0]?.universe ?? []).map(a => ({ ...a, name: `${String(a.name)}-PERP` }));
             ctxs = meta[1] ?? [];
-            mids = allMids;
+            marginTables = meta[0]?.marginTables;
+            for (const [coin, px] of Object.entries(allMids ?? {}))
+                mids[`${coin}-PERP`] = px;
+        }
+        // `marginTables` rides along in the SAME metaAndAssetCtxs response we
+        // already fetch — zero extra network calls. Shape: [[tableId, {description,
+        // marginTiers: [{lowerBound, maxLeverage}]}], ...]. `universe[i].maxLeverage`
+        // is only the TOP tier: 36 of 233 symbols step down above a notional
+        // threshold (BTC 40x, then 20x above $150M), so a pre-trade check that reads
+        // the flat value alone waves through orders the venue rejects.
+        const tierMap = new Map();
+        if (Array.isArray(marginTables)) {
+            for (const entry of marginTables) {
+                if (!Array.isArray(entry) || entry.length < 2)
+                    continue;
+                const id = Number(entry[0]);
+                const tiers = entry[1]?.marginTiers;
+                if (!Number.isFinite(id) || !Array.isArray(tiers))
+                    continue;
+                const parsed = tiers
+                    .map((t) => ({ lowerBound: Number(t.lowerBound), maxLeverage: Number(t.maxLeverage) }))
+                    .filter((t) => Number.isFinite(t.lowerBound) && Number.isFinite(t.maxLeverage) && t.maxLeverage > 0)
+                    .sort((a, b) => a.lowerBound - b.lowerBound);
+                if (parsed.length > 0)
+                    tierMap.set(id, parsed);
+            }
         }
         // Rebuild asset map if empty (fallback — normally populated by init/_loadAssetMap)
         if (this._assetMap.size === 0 && !this._dex) {
@@ -312,16 +765,21 @@ export class HyperliquidAdapter {
         const result = universe.map((asset, i) => {
             const ctx = (ctxs[i] ?? {});
             const sym = String(asset.name);
-            const szDec = this._szDecimalsMap.get(sym) ?? (asset.szDecimals !== undefined ? Number(asset.szDecimals) : undefined);
+            const szDec = this._szDecimalsMap.get(sym) ?? (asset.szDecimals !== undefined ? Number(asset.szDecimals) : null);
             return {
                 symbol: sym,
                 markPrice: String(ctx.markPx ?? mids[sym] ?? "0"),
-                indexPrice: String(ctx.oraclePx ?? "0"),
+                indexPrice: ctx.oraclePx != null ? String(ctx.oraclePx) : null,
                 fundingRate: ctx.funding != null ? String(ctx.funding) : null,
-                volume24h: String(ctx.dayNtlVlm ?? "0"),
-                openInterest: String(ctx.openInterest ?? "0"),
+                volume24h: ctx.dayNtlVlm != null ? String(ctx.dayNtlVlm) : null,
+                openInterest: ctx.openInterest != null ? String(ctx.openInterest) : null,
                 maxLeverage: Number(asset.maxLeverage ?? 50),
                 sizeDecimals: szDec,
+                // HL has no separate lot-size field; the step is implied by szDecimals.
+                stepSize: null,
+                // HL funding is uniform (venue definition), not per-market.
+                fundingHours: null,
+                marginTiers: tierMap.get(Number(asset.marginTableId)) ?? null,
             };
         });
         this._marketsCache = result;
@@ -331,20 +789,16 @@ export class HyperliquidAdapter {
     async getOrderbook(symbol) {
         let levels;
         if (this._dex) {
-            // HIP-3 dex: SDK's getL2Book() doesn't support dex parameter
-            // Resolve symbol to full dex-prefixed name (e.g. "US500" → "km:US500")
-            const resolved = this.resolveSymbol(symbol.toUpperCase());
-            // Ensure dex prefix is present (API requires it)
-            const coin = resolved.includes(":") ? resolved : `${this._dex}:${resolved}`;
+            // HIP-3 dex: full dex-prefixed coin (e.g. "US500" → "km:US500") + dex param
             const book = await this._infoPost({
                 type: "l2Book",
-                coin,
+                coin: this._venueCoin(symbol),
                 dex: this._dex,
             });
             levels = book?.levels ?? [[], []];
         }
         else {
-            const book = await this.sdk.info.getL2Book(symbol.toUpperCase());
+            const book = await this._infoPost({ type: "l2Book", coin: this._venueCoin(symbol) });
             levels = book?.levels ?? [[], []];
         }
         return {
@@ -358,47 +812,66 @@ export class HyperliquidAdapter {
             ]),
         };
     }
+    /**
+     * Venue coin for a symbol: native perps drop the "-PERP" display suffix ("BTC-PERP" →
+     * "BTC"); HIP-3 coins carry the dex prefix ("US500" → "km:US500").
+     */
+    _venueCoin(symbol) {
+        const resolved = this.resolveSymbol(symbol.toUpperCase());
+        if (this._dex)
+            return resolved.includes(":") ? resolved : `${this._dex}:${resolved}`;
+        return resolved.replace(/-PERP$/, "");
+    }
+    /** Display symbol for a venue coin: a native perp coin "BTC" → "BTC-PERP"; anything else unchanged. */
+    _displaySymbol(coin) {
+        return !this._dex && this._assetMap.has(`${coin}-PERP`) ? `${coin}-PERP` : coin;
+    }
     ensureAddress() {
         if (!this._address) {
             throw new Error("No private key configured — account data unavailable. Run: perp setup");
         }
     }
+    /** The in-flight clearinghouseState read: parallel callers (getBalance + getPositions) share one request. */
+    _chsInFlight = null;
     /** Read-through cached clearinghouseState — returns cached data if fresh */
     async _getClearinghouseState() {
         this.ensureAddress();
-        const { withCache, TTL_ACCOUNT } = await import("../cache.js");
-        const key = this._dex ? `acct:hl:chs:${this._address}:${this._dex}` : `acct:hl:chs:${this._address}`;
-        return withCache(key, TTL_ACCOUNT, async () => {
+        if (this._chsInFlight !== null)
+            return this._chsInFlight;
+        const key = this._dex ? `acct:hl:${this._network}:chs:${this._address}:${this._dex}` : `acct:hl:${this._network}:chs:${this._address}`;
+        const p = withCache(key, TTL_ACCOUNT, async () => {
             const state = this._dex
                 ? await this._infoPost({ type: "clearinghouseState", user: this._address, dex: this._dex })
-                : await this.sdk.info.perpetuals.getClearinghouseState(this._address);
+                : await this._infoPost({ type: "clearinghouseState", user: this._address });
             return state;
         });
+        this._chsInFlight = p;
+        const clear = () => { if (this._chsInFlight === p)
+            this._chsInFlight = null; };
+        p.then(clear, clear);
+        return p;
     }
     /**
      * Read the user's account abstraction mode from HL.
      *
-     * Returns the canonical mode used to branch collateral accounting:
-     *   - "unified"   → spot clearinghouseState is the truth source (USDC total
-     *                   is unified across spot + perp). app.hyperliquid.xyz default.
-     *   - "standard"  → perp clearinghouseState is the truth source. Required
-     *                   mode for builder fee accrual.
-     *   - "portfolio" → multi-asset cross-collateral; for now treated like
-     *                   unified (spot truth). Refine when portfolio margin GA.
+     * Abstraction is a property of the USER (not of a dex): it is always queried,
+     * HIP-3 dex adapters included.
+     *   - "unified"   → spot clearinghouseState is the truth source (one balance per
+     *                   collateral token, shared by spot and every perp dex).
+     *   - "portfolio" → multi-asset cross-collateral; balances also live in spot state.
+     *   - "standard"  → perp clearinghouseState is the truth source (venue "disabled").
+     *   - "default"   → the user never set a mode. Not assumed to be either: balances
+     *                   are read from the perp state and getBalance() warns when that
+     *                   reads 0 while spot holds the collateral token.
      *
-     * Per SSOT Rule #2: an unrecognized venue response throws — no silent
-     * default. HIP-3 dex accounts (`this._dex` set) bypass the lookup since
-     * cross margin scopes per-DEX in standard semantics.
+     * Per SSOT Rule #2: an unrecognized venue response throws — no silent default.
      *
-     * Endpoint: `POST /info {"type":"userAbstraction","user":"0x..."}` →
-     * returns one of `"unifiedAccount" | "disabled" | "portfolioMargin"`.
+     * Endpoint: `POST /info {"type":"userAbstraction","user":"0x..."}`.
      */
-    async _getAbstractionMode() {
-        if (this._dex)
-            return "standard";
+    async _getAbstractionMode(opts = {}) {
         this.ensureAddress();
-        const { withCache, TTL_ACCOUNT } = await import("../cache.js");
-        return withCache(`acct:hl:abstraction:${this._address}`, TTL_ACCOUNT, async () => {
+        const key = `${hlAbstractionCachePrefix(this._network)}${this._address.toLowerCase()}`;
+        return (opts.fresh === true ? fetchAndCache : withCache)(key, HL_ABSTRACTION_TTL_MS, async () => {
             const raw = (await this._infoPost({ type: "userAbstraction", user: this._address }));
             if (raw === "unifiedAccount")
                 return "unified";
@@ -406,89 +879,129 @@ export class HyperliquidAdapter {
                 return "portfolio";
             if (raw === "disabled")
                 return "standard";
-            // "default" is the implicit pre-set value HL returns when a user has
-            // never invoked `userSetAbstraction`. Per HL docs the four modes are
-            // Standard / Unified / Portfolio / (legacy) DEX abstraction. The set
-            // API only accepts the latter three; Standard is the de-facto baseline
-            // for unset accounts. Map "default" → "standard" so accounting branches
-            // pick the perp clearinghouse path. Users can opt into unified explicitly
-            // via `wallet manage account-mode unified`.
             if (raw === "default")
-                return "standard";
-            // "dexAbstraction" is HL's legacy fourth mode, slated for deprecation
-            // but still returned by the venue for some users. Per HL docs the spot
-            // pool acts as collateral (same accounting semantics as unified), so
-            // route through the unified branch rather than throwing.
+                return "default";
+            // "dexAbstraction" is HL's discontinued fourth mode, still returned for some users. It is
+            // NOT unified: "USDC balances default to perps balance, all other collateral defaults to
+            // spot balance" (docs trading/account-abstraction-modes). Handled explicitly in getBalance().
             if (raw === "dexAbstraction")
-                return "unified";
+                return "dexAbstraction";
             throw new PerpError("INVALID_PARAMS", `UNKNOWN_ACCOUNT_MODE: HL returned unrecognized userAbstraction mode: ${JSON.stringify(raw)}`, { remediation: "Check app.hyperliquid.xyz Settings → Account Mode" });
         });
     }
-    /** Cached spot clearinghouse state — shared between getBalance() and HyperliquidSpotAdapter */
-    async _getSpotClearinghouseState() {
+    /** Collateral token index of this adapter's perp dex (info `meta{dex}.collateralToken`; 0 = USDC on native perps). */
+    _collateralTokenIdx = null;
+    async _getCollateralToken() {
+        if (this._collateralTokenIdx !== null)
+            return this._collateralTokenIdx;
+        const meta = await this._metaCached();
+        const idx = meta?.collateralToken;
+        if (typeof idx !== "number" || !Number.isInteger(idx) || idx < 0) {
+            throw new PerpError("EXCHANGE_ERROR", `Hyperliquid meta${this._dex ? `{dex:${this._dex}}` : ""} has no collateralToken (got ${JSON.stringify(idx)})`, {
+                exchange: "hyperliquid",
+            });
+        }
+        this._collateralTokenIdx = idx;
+        return idx;
+    }
+    /** Cached spot clearinghouse state (raw venue shape) — shared between getBalance() and HyperliquidSpotAdapter */
+    async _getSpotClearinghouseState(opts) {
         this.ensureAddress();
-        const { withCache, TTL_ACCOUNT } = await import("../cache.js");
-        return withCache(`acct:hl:spot_chs:${this._address}`, TTL_ACCOUNT, async () => {
-            return await this.sdk.info.spot.getSpotClearinghouseState(this._address);
-        });
+        const { withCache, fetchAndCache, TTL_ACCOUNT } = await import("../cache.js");
+        const fetcher = async () => await this._infoPost({ type: "spotClearinghouseState", user: this._address });
+        const key = `acct:hl:${this._network}:spot_chs:${this._address}`;
+        // fresh: bypass the shared TTL cache (fill measurement / post-trade verification).
+        return opts?.fresh === true ? fetchAndCache(key, TTL_ACCOUNT, fetcher) : withCache(key, TTL_ACCOUNT, fetcher);
+    }
+    /** Spot balance row of this dex's collateral token (matched by token index, not by coin name); null = none held. */
+    async _spotCollateralRow() {
+        const [spotState, token] = await Promise.all([this._getSpotClearinghouseState(), this._getCollateralToken()]);
+        const balances = (spotState?.balances ?? []);
+        const row = balances.find((b) => Number(b.token) === token) ?? null;
+        return { row, balances, token };
     }
     async getBalance() {
         const state = await this._getClearinghouseState();
         const s = state;
         const margin = (s?.marginSummary ?? {});
         const cross = (s?.crossMarginSummary ?? {});
-        const marginUsed = Number(margin.totalMarginUsed ?? cross.totalMarginUsed ?? 0);
+        const marginUsed = parseFiniteVenueNumber(margin.totalMarginUsed ?? cross.totalMarginUsed, "marginSummary.totalMarginUsed", "hyperliquid");
         // Sum unrealized PnL directly from positions (reliable for both main + dex accounts)
         const positions = (s?.assetPositions ?? []);
         let unrealizedPnl = 0;
         for (const entry of positions) {
             const pos = (entry.position ?? entry);
-            unrealizedPnl += Number(pos.unrealizedPnl ?? 0);
+            unrealizedPnl += parseFiniteVenueNumber(pos.unrealizedPnl, "position.unrealizedPnl", "hyperliquid");
         }
         let equity;
         let available;
-        // Branch by user's account abstraction mode (Rule #2: no silent fallback).
-        // - "unified" / "portfolio": spot USDC total = true equity; perp margin
-        //   is held against the same USDC pool, so adding both double-counts.
-        // - "standard": separate perp/spot accounting; perp clearinghouse is the
-        //   only collateral source. Required mode for builder fee accrual.
-        // HIP-3 dex accounts (this._dex) always use standard semantics.
+        // Branch by the user's account abstraction mode (Rule #2: no silent fallback).
+        // - "unified" / "portfolio": per HL docs, API users see all balances and holds
+        //   in the spot clearinghouse state; the dex's collateral token row (by token
+        //   index from meta{dex}.collateralToken) is the equity. Adding perp margin
+        //   would double-count.
+        // - "standard" / "default": perp clearinghouse (per dex) is the collateral source.
         //
-        // Portfolio-margin mode: per HL portfolio-margin docs, eligible collateral
-        // includes HYPE, BTC, USDH, USDC. We currently use USDC-only as a minimum
-        // viable baseline (mark-priced multi-asset accounting requires fetching
-        // spot mark prices and is deferred to a follow-up). Emit a stderr note so
-        // users see the breakdown when non-USDC collateral is present.
+        // Portfolio-margin mode: eligible collateral includes HYPE, BTC, USDT besides
+        // USDC. Only the collateral token is counted; a stderr note lists the rest.
         const mode = await this._getAbstractionMode();
-        if (mode === "unified" || mode === "portfolio") {
-            const spotState = await this._getSpotClearinghouseState();
-            const balances = (spotState?.balances ?? []);
-            const usdc = balances.find((b) => String(b.coin).startsWith("USDC"));
-            const spotTotal = Number(usdc?.total ?? 0);
-            const spotHold = Number(usdc?.hold ?? 0);
+        // dexAbstraction (discontinued): USDC (token 0) lives in the NATIVE perp balance, any other
+        // collateral token in spot. Native perps → the perp state below. A HIP-3 dex with non-USDC
+        // collateral → its spot row. A USDC-collateral HIP-3 dex is refused: its dex state is not the
+        // balance ("Cross margin on HIP-3 DEXs does not behave intuitively for DEX abstraction users").
+        let spotIsTruth = mode === "unified" || mode === "portfolio";
+        if (mode === "dexAbstraction" && this._dex) {
+            if (await this._getCollateralToken() === 0) {
+                throw new PerpError("NOT_IMPLEMENTED", `Hyperliquid account mode "dexAbstraction" (discontinued by the venue): the USDC balance of HIP-3 dex "${this._dex}" cannot be read reliably`, {
+                    exchange: "hyperliquid",
+                    remediation: "Switch the account mode first: perp -e hyperliquid wallet manage account-mode unified (or standard)",
+                });
+            }
+            spotIsTruth = true;
+        }
+        if (spotIsTruth) {
+            const { row, balances, token } = await this._spotCollateralRow();
+            const coin = row === null ? `token#${token}` : String(row.coin);
+            const spotTotal = parseFiniteVenueNumber(row?.total, `spotBalance.${coin}.total`, "hyperliquid");
+            const spotHold = parseFiniteVenueNumber(row?.hold, `spotBalance.${coin}.hold`, "hyperliquid");
             equity = spotTotal;
             available = spotTotal - spotHold;
             if (mode === "portfolio") {
-                const PORTFOLIO_COLLATERAL = ["HYPE", "BTC", "USDH"];
-                const nonUsdc = balances.filter((b) => {
-                    const coin = String(b.coin);
-                    if (coin.startsWith("USDC"))
+                // Eligible collateral per trading/account-abstraction-modes.md ("eligible
+                // assets, which are currently HYPE, BTC, USDC, USDT").
+                const PORTFOLIO_COLLATERAL = ["HYPE", "BTC", "USDT"];
+                const others = balances.filter((b) => {
+                    if (Number(b.token) === token)
                         return false;
-                    if (Number(b.total ?? 0) <= 0)
+                    const c = String(b.coin);
+                    // Reject NaN/empty here too — venue payload corruption shouldn't
+                    // silently filter a token in or out.
+                    const total = parseFiniteVenueNumber(b.total, `spotBalance.${c}.total`, "hyperliquid");
+                    if (total <= 0)
                         return false;
-                    return PORTFOLIO_COLLATERAL.some((c) => coin === c || coin.startsWith(`${c}-`));
+                    return PORTFOLIO_COLLATERAL.some((p) => c === p || c.startsWith(`${p}-`));
                 });
-                if (nonUsdc.length > 0) {
-                    const summary = nonUsdc.map((b) => `${b.coin}=${b.total}`).join(", ");
-                    process.stderr.write(`[hl] portfolio mode: non-USDC collateral present but not counted in equity (${summary}). ` +
-                        `Equity reflects USDC only; full multi-asset accounting pending.\n`);
+                if (others.length > 0) {
+                    const summary = others.map((b) => `${b.coin}=${b.total}`).join(", ");
+                    process.stderr.write(`[hl] portfolio mode: non-${coin} collateral present but not counted in equity (${summary}). ` +
+                        `Equity reflects ${coin} only; full multi-asset accounting pending.\n`);
                 }
             }
         }
         else {
-            // mode === "standard"
-            equity = Number(margin.accountValue ?? cross.accountValue ?? 0);
-            available = Number(s?.withdrawable ?? 0);
+            equity = parseFiniteVenueNumber(margin.accountValue ?? cross.accountValue, "marginSummary.accountValue", "hyperliquid");
+            available = parseFiniteVenueNumber(s?.withdrawable, "withdrawable", "hyperliquid");
+            if (mode === "default" && equity === 0) {
+                // Unset mode: do not assume unified. If the perp side reads 0 while spot holds
+                // the collateral token, say so instead of reporting an empty account silently.
+                const { row, token } = await this._spotCollateralRow();
+                const spotTotal = parseFiniteVenueNumber(row?.total, `spotBalance.token#${token}.total`, "hyperliquid");
+                if (spotTotal > 0) {
+                    process.stderr.write(`[hl] account mode is unset ("default"): perp equity${this._dex ? ` on dex ${this._dex}` : ""} is 0 while spot holds ${spotTotal} ${String(row?.coin)}. ` +
+                        `That spot balance is not perp collateral here. Either switch the account to unified ` +
+                        `(perp wallet manage account-mode unified) or move it: perp -e hyperliquid trade spot-transfer to-perp <amount>\n`);
+                }
+            }
         }
         return {
             equity: String(equity),
@@ -503,56 +1016,158 @@ export class HyperliquidAdapter {
         return positions
             .filter((p) => {
             const pos = (p.position ?? p);
-            return Number(pos.szi ?? 0) !== 0;
+            return parseFiniteVenueNumber(pos.szi, "position.szi", "hyperliquid") !== 0;
         })
             .map((p) => {
             const pos = (p.position ?? p);
-            const szi = Number(pos.szi ?? 0);
+            const szi = parseFiniteVenueNumber(pos.szi, "position.szi", "hyperliquid");
+            const positionValue = pos.positionValue !== undefined && pos.positionValue !== null
+                ? parseFiniteVenueNumber(pos.positionValue, "position.positionValue", "hyperliquid")
+                : 0;
             return {
-                symbol: String(pos.coin ?? ""),
+                symbol: this._displaySymbol(String(pos.coin ?? "")),
                 side: szi > 0 ? "long" : "short",
                 size: String(Math.abs(szi)),
                 entryPrice: String(pos.entryPx ?? "0"),
-                markPrice: String(szi !== 0 && pos.positionValue && Number(pos.positionValue) !== 0
-                    ? Number(pos.positionValue) / Math.abs(szi)
-                    : pos.markPx ?? "0"),
-                liquidationPrice: String(pos.liquidationPx ?? "N/A"),
+                // clearinghouseState has no per-position mark: positionValue / |szi| is computed, so it is
+                // formatted (no "2727.2000000000003").
+                markPrice: szi !== 0 && positionValue !== 0
+                    ? formatComputedPrice(positionValue / Math.abs(szi))
+                    : String(pos.markPx ?? "0"),
+                liquidationPrice: pos.liquidationPx != null ? String(pos.liquidationPx) : null,
                 unrealizedPnl: String(pos.unrealizedPnl ?? "0"),
-                leverage: Number(pos.leverage?.value ?? 1),
+                leverage: parseFiniteVenueNumber(pos.leverage?.value, "position.leverage.value", "hyperliquid", { defaultValue: 1 }),
             };
         });
     }
+    /**
+     * The leverage this account applies to `symbol`, position or not — info `activeAssetData`
+     * {user, coin} → `"leverage": { "type": "cross", "value": 3 }` (docs info-endpoint/perpetuals).
+     * Unreadable → EXCHANGE_ERROR.
+     */
+    async marketLeverage(symbol) {
+        this.ensureAddress();
+        const coin = this._venueCoin(symbol);
+        const r = await this._infoPost({ type: "activeAssetData", user: this._address, coin });
+        const v = r?.leverage?.value;
+        if (typeof v !== "number" || !(v >= 1)) {
+            throw new PerpError("EXCHANGE_ERROR", `Hyperliquid activeAssetData ${coin}: unreadable leverage ${JSON.stringify(r?.leverage ?? null)}`, { exchange: "hyperliquid" });
+        }
+        return v;
+    }
+    /**
+     * Per-market leverage / margin mode:
+     *  - every market with a position: the `leverage` object of its `assetPositions` entry of info
+     *    `clearinghouseState` (docs info-endpoint/perpetuals: `"leverage": { "rawUsd": "-95.059824",
+     *    "type": "isolated", "value": 20 }`);
+     *  - markets WITHOUT a position the account traded: the HL_SETTINGS_FILL_MARKETS most recently
+     *    traded perp markets of this adapter's dex in info `userFills` ("at most 2000 most recent
+     *    fills"; spot "@<i>" / "BASE/QUOTE", HIP-4 "#<enc>", other dexes and delisted coins are not
+     *    markets of this adapter and are skipped), each read with info `activeAssetData` {user, coin}
+     *    → `"leverage": { "type": "cross", "value": 3 }` (docs info-endpoint/perpetuals; live
+     *    2026-10-13 `{"type":"cross","value":20}` for an account that never set ETH).
+     * Weight (docs "Rate limits and user limits"): clearinghouseState 2 + userFills 20 (+1 per 20
+     * fills) + activeAssetData 20 per market — bounded by HL_SETTINGS_FILL_MARKETS.
+     * An unreadable leverage → EXCHANGE_ERROR.
+     */
+    async getMarketSettings() {
+        const state = await this._getClearinghouseState();
+        if (!Array.isArray(state.assetPositions)) {
+            throw new PerpError("EXCHANGE_ERROR", "Hyperliquid clearinghouseState has no assetPositions list — per-market settings unknown", { exchange: "hyperliquid" });
+        }
+        const leverageOf = (lev, what) => {
+            const l = lev;
+            if ((l?.type !== "cross" && l?.type !== "isolated") || typeof l.value !== "number" || !(l.value > 0)) {
+                throw new PerpError("EXCHANGE_ERROR", `Hyperliquid ${what}: unreadable leverage ${JSON.stringify(lev ?? null)}`, { exchange: "hyperliquid" });
+            }
+            return { leverage: l.value, marginMode: l.type };
+        };
+        const rows = state.assetPositions.map((p) => {
+            const pos = (p.position ?? p);
+            return { coin: String(pos.coin), ...leverageOf(pos.leverage, `position ${String(pos.coin)}`) };
+        });
+        const held = new Set(rows.map(r => r.coin));
+        const fills = await this._infoPost({ type: "userFills", user: this._address });
+        if (!Array.isArray(fills)) {
+            throw new PerpError("EXCHANGE_ERROR", `Hyperliquid userFills returned no list (got ${JSON.stringify(fills).slice(0, 160)})`, { exchange: "hyperliquid" });
+        }
+        const listed = (coin) => this._dex ? coin.startsWith(`${this._dex}:`) && this._assetMap.has(coin) : this._assetMap.has(`${coin}-PERP`);
+        const traded = [];
+        for (const f of [...fills].sort((a, b) => Number(b.time) - Number(a.time))) {
+            const coin = String(f.coin);
+            if (traded.length >= HL_SETTINGS_FILL_MARKETS)
+                break;
+            if (!held.has(coin) && !traded.includes(coin) && listed(coin))
+                traded.push(coin);
+        }
+        for (const coin of traded) {
+            const r = await this._infoPost({ type: "activeAssetData", user: this._address, coin });
+            rows.push({ coin, ...leverageOf(r?.leverage, `activeAssetData ${coin}`) });
+        }
+        return rows.map(r => ({ symbol: this._displaySymbol(r.coin), leverage: r.leverage, marginMode: r.marginMode }));
+    }
+    /**
+     * Open orders from info `frontendOpenOrders` (native perps, or the HIP-3 dex): unlike
+     * `openOrders` it labels trigger orders (isTrigger, orderType "Stop Market" / "Take Profit
+     * Limit" …, triggerPx), so stops / TP / SL are listed as such and cancel-all / flatten cancel
+     * them. `type` = the venue orderType for a trigger order, else "limit".
+     */
     async getOpenOrders() {
         this.ensureAddress();
-        if (this._dex) {
-            // HIP-3 dex: use frontendOpenOrders with dex parameter
-            const orders = await this._infoPost({
-                type: "frontendOpenOrders", user: this._address, dex: this._dex,
+        const req = { type: "frontendOpenOrders", user: this._address };
+        if (this._dex)
+            req.dex = this._dex;
+        const orders = await this._infoPost(req);
+        // Perp orders only. Without a dex, frontendOpenOrders also lists the account's SPOT orders
+        // (coin "@<index>" or "<BASE>/<QUOTE>"): they belong to the spot commands — a perp
+        // cancel-all / flatten must neither cancel nor be failed by a resting spot limit.
+        if (!Array.isArray(orders)) {
+            throw new PerpError("EXCHANGE_ERROR", "Hyperliquid frontendOpenOrders returned no array", { exchange: "hyperliquid", remediation: "Retry: perp -e hyperliquid account orders" });
+        }
+        // Rule #2: a row without its oid / limitPx / sz is unreadable — never listed as id "" or price/size "0".
+        const field = (o, k) => {
+            const v = o[k];
+            if ((typeof v === "number" && Number.isFinite(v)) || (typeof v === "string" && v.trim() !== ""))
+                return String(v);
+            throw new PerpError("EXCHANGE_ERROR", `Hyperliquid frontendOpenOrders row without ${k}: ${JSON.stringify(o).slice(0, 200)}`, {
+                exchange: "hyperliquid", remediation: "Retry: perp -e hyperliquid account orders",
             });
-            return (orders ?? []).map((o) => ({
-                orderId: String(o.oid ?? ""),
-                symbol: String(o.coin ?? ""),
-                side: String(o.side) === "B" ? "buy" : String(o.side) === "A" ? "sell" : String(o.side).toLowerCase(),
-                price: String(o.limitPx ?? "0"),
-                size: String(o.sz ?? "0"),
-                filled: "0",
-                status: "open",
-                type: "limit",
-            }));
-        }
-        const orders = await this.sdk.info.getUserOpenOrders(this._address);
-        return (orders ?? []).map((o) => ({
-            orderId: String(o.oid ?? ""),
-            symbol: String(o.coin ?? ""),
-            // SDK convertSymbolsInObject already converts "B"→"buy", "A"→"sell"
-            side: String(o.side) === "B" ? "buy" : String(o.side) === "A" ? "sell" : o.side,
-            price: String(o.limitPx ?? "0"),
-            size: String(o.sz ?? "0"),
+        };
+        return orders.filter((o) => !hlIsSpotCoin(String(o.coin ?? ""))).map((o) => ({
+            orderId: field(o, "oid"),
+            symbol: this._dex ? String(o.coin ?? "") : this._displaySymbol(String(o.coin ?? "")),
+            side: String(o.side) === "B" ? "buy" : String(o.side) === "A" ? "sell" : String(o.side).toLowerCase(),
+            price: field(o, "limitPx"),
+            size: field(o, "sz"),
             filled: "0",
             status: "open",
-            type: "limit",
+            type: o.isTrigger === true && typeof o.orderType === "string" ? o.orderType : "limit",
+            triggerPrice: o.isTrigger === true && Number(o.triggerPx) > 0 ? String(o.triggerPx) : null,
         }));
     }
+    /** HL order id for a cancel: a decimal integer that is exactly representable (else INVALID_PARAMS, nothing sent). */
+    /**
+     * A Hyperliquid client order id (cloid) as sent / queried: "0x" + 32 lowercase hex chars
+     * (exchange-endpoint docs: `c` "an optional 128 bit hex string, e.g.
+     * 0x1234567890abcdef1234567890abcdef"). Anything else → INVALID_PARAMS, nothing sent.
+     */
+    static requireCloid(cloid) {
+        if (!HL_CLOID_RE.test(cloid)) {
+            throw new PerpError("INVALID_PARAMS", `Hyperliquid client order id "${cloid}" must be a 128-bit hex cloid: 0x + 32 lowercase hex chars`, {
+                exchange: "hyperliquid", remediation: "Pass e.g. --client-id 0x1234567890abcdef1234567890abcdef, or use --auto-id (a valid cloid is generated and reported)",
+            });
+        }
+        return cloid;
+    }
+    _oidOf(orderId) {
+        const n = Number(orderId);
+        if (!/^\d+$/.test(orderId) || !Number.isSafeInteger(n)) {
+            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 account orders -e hyperliquid",
+            });
+        }
+        return n;
+    }
     async _invalidateAccountCache() {
         try {
             const { invalidateCache } = await import("../cache.js");
@@ -569,76 +1184,134 @@ export class HyperliquidAdapter {
     _validateOrderFill(result, symbol, side, requestedSize) {
         const r = result;
         const statuses = r?.response?.data?.statuses;
+        const what = `market ${side} ${requestedSize} ${symbol}`;
         if (!statuses || statuses.length === 0) {
-            throw new Error(`Market ${side} ${symbol}: no order status in response`);
+            throw orderOutcomeUnknown("hyperliquid", what, new Error("no order status in response"));
         }
         const st = statuses[0];
         if (st.error) {
-            throw new Error(`Market ${side} ${symbol}: ${st.error}`);
+            // Explicit per-order venue rejection: definitely not placed.
+            throw new PerpError("ORDER_REJECTED", `Market ${side} ${symbol}: ${st.error}`, { exchange: "hyperliquid" });
         }
         const filled = st.filled;
-        if (!filled || Number(filled.totalSz ?? 0) === 0) {
-            throw new Error(`Market ${side} ${symbol}: order not filled (0 of ${requestedSize}). Check price/liquidity.`);
+        if (!filled && st.resting !== undefined) {
+            // An IOC reported resting is live on the book — outcome NOT definite.
+            throw orderOutcomeUnknown("hyperliquid", what, new Error("the IOC was reported resting on the book"));
+        }
+        if (!filled) {
+            // No filled / resting / error field: unexpected shape — outcome not definite.
+            throw orderOutcomeUnknown("hyperliquid", what, new Error("unexpected order status shape (no filled/resting/error)"));
+        }
+        if (filled.totalSz === undefined || !Number.isFinite(Number(filled.totalSz))) {
+            throw orderOutcomeUnknown("hyperliquid", what, new Error("filled status without a readable totalSz"));
+        }
+        if (Number(filled.totalSz) === 0) {
+            // IOC zero-fill: the venue cancelled the remainder — nothing traded (definite).
+            throw new PerpError("ORDER_REJECTED", `Market ${side} ${symbol}: order not filled (0 of ${requestedSize}). Check price/liquidity.`, { exchange: "hyperliquid" });
         }
     }
+    /**
+     * Market order = slippage-bounded IOC limit (design §13.2, §13.10 #1/#5) for
+     * native perps and HIP-3 dexes alike. Replaces the SDK's marketOpen/marketClose
+     * (hidden built-in slippage) and the former HIP-3 5% constant.
+     *
+     * Reference price (the single declared source, §13.10 #5): the l2Book mid
+     * (best bid + best ask) / 2 of this coin — see referencePrice(). No runtime
+     * substitute (mark, allMids, last trade): a missing side → PRICE_STALE before
+     * anything is sent. Protection = reference ± opts.slippage.bps, aligned toward
+     * crossing on HL's price grid (hlProtectionPrice, max 6 − szDecimals decimals).
+     *
+     * reduceOnly is sent as the order's `r` flag: the venue can only reduce the
+     * position with it (never open/flip), so the caller's side is used as given.
+     */
     async marketOrder(symbol, side, size, opts) {
-        this.ensureSigner();
-        if (this._dex) {
-            const r = await this._dexMarketOrder(symbol, side, size);
-            this._validateOrderFill(r, symbol, side, size);
-            await this._invalidateAccountCache();
-            return r;
-        }
-        // Suppress SDK console.log noise (slippage price, decimals, order details)
-        const origLog = console.log;
-        console.log = () => { };
+        // Everything before the signed POST /exchange (signer, `meta` asset id, l2Book reference
+        // price, builder approval read) is pre-send: a failed read there (429, transport) is a
+        // definite "not sent" (orderNotSent), never a retryable error with an unknown write outcome.
+        let action;
+        let sentSize;
+        let protection;
+        const cloid = opts.clientOrderId === undefined ? null : HyperliquidAdapter.requireCloid(opts.clientOrderId);
         try {
-            const result = await this.sdk.custom.marketOpen(symbol.toUpperCase(), side === "buy", parseFloat(size));
-            this._validateOrderFill(result, symbol, side, size);
-            await this._invalidateAccountCache();
-            return result;
+            this.ensureSigner();
+            const assetIndex = await this.getAssetIndex(symbol.toUpperCase());
+            const szDec = this.getSzDecimals(symbol);
+            // Floor to the szDecimals lot (never round up past the requested size); 0 → SIZE_TOO_SMALL.
+            sentSize = floorSize(size, hlSizeStep(szDec));
+            protection = await this.computeProtectionPrice(symbol, side, opts.slippage);
+            action = await this._orderAction([this._orderWire({
+                    assetIndex,
+                    isBuy: side === "buy",
+                    price: protection.protectionPrice,
+                    size: sentSize,
+                    orderType: { limit: { tif: "Ioc" } },
+                    reduceOnly: opts.reduceOnly,
+                    cloid,
+                })], "na", assetIndex);
         }
-        finally {
-            console.log = origLog;
+        catch (e) {
+            throw orderNotSent("hyperliquid", `market ${side} ${size} ${symbol.toUpperCase()}`, e);
         }
+        const result = await this._signAndSendAction(action);
+        // Per-order verdict: error → ORDER_REJECTED, zero fill → ORDER_REJECTED, resting/unknown → throws.
+        this._validateOrderFill(result, symbol, side, sentSize);
+        await this._invalidateAccountCache();
+        // The protection actually sent rides along with the raw response (like Lighter's
+        // `protection`) so a TradingV2 wrapper records it in execution; `sentSize` is the
+        // size actually sent (floored to szDecimals) that verification compares against.
+        return { ...result, protection, sentSize, ...(cloid !== null ? { clientOrderId: cloid } : {}) };
     }
     /**
-     * Place a market order on a HIP-3 deployed dex.
-     * Bypasses SDK's symbolConversion (which only knows native perps)
-     * and constructs + signs the order action directly.
+     * The single declared reference price for market-type protection prices:
+     * l2Book mid = (best bid + best ask) / 2. Works for native perps and HIP-3
+     * (getOrderbook passes the dex). Either side missing / non-positive → PRICE_STALE.
      */
-    async _dexMarketOrder(symbol, side, size) {
-        const assetIndex = await this.getAssetIndex(symbol.toUpperCase());
-        const szDec = this.getSzDecimals(symbol);
-        // Get current mark price from dex meta (lookup by coin name, not array index)
-        const resolved = this.resolveSymbol(symbol.toUpperCase());
-        const coin = resolved.includes(":") ? resolved : `${this._dex}:${resolved}`;
-        const meta = await this._infoPost({
-            type: "metaAndAssetCtxs",
-            dex: this._dex,
-        });
-        // Find local index by matching coin name in universe
-        const localIdx = meta[0]?.universe?.findIndex(a => a.name === coin) ?? -1;
-        const ctx = localIdx >= 0 ? (meta[1] ?? [])[localIdx] : undefined;
-        const midPrice = Number(ctx?.markPx ?? 0);
-        if (midPrice <= 0)
-            throw new Error(`Cannot get price for ${symbol} on dex ${this._dex}`);
-        // HL official rounding: 5 significant figures, max 6 decimals for perps
-        const MAX_DECIMALS_PERP = 6;
-        const slippage = 0.05;
-        const isBuy = side === "buy";
-        const slippagePrice = isBuy ? midPrice * (1 + slippage) : midPrice * (1 - slippage);
-        const limitPrice = slippagePrice > 100_000
-            ? String(Math.round(slippagePrice))
-            : Number(Number(slippagePrice.toPrecision(5)).toFixed(Math.max(0, MAX_DECIMALS_PERP - szDec))).toString();
-        return this._rawPlaceOrder({
-            assetIndex,
-            isBuy,
-            price: limitPrice,
-            size: Number(size).toFixed(szDec),
-            orderType: { limit: { tif: "Ioc" } },
-            reduceOnly: false,
-        });
+    async referencePrice(symbol) {
+        const book = await this.getOrderbook(symbol);
+        const bid = Number(book.bids[0]?.[0]);
+        const ask = Number(book.asks[0]?.[0]);
+        if (!(bid > 0) || !(ask > 0) || !Number.isFinite(bid) || !Number.isFinite(ask)) {
+            throw new PerpError("PRICE_STALE", `Hyperliquid ${symbol.toUpperCase()}${this._dex ? ` (dex ${this._dex})` : ""}: no two-sided l2Book to derive the mid reference price`, {
+                exchange: "hyperliquid",
+                remediation: "Retry when the book has both bids and asks, or place a limit order",
+            });
+        }
+        return (bid + ask) / 2;
+    }
+    /**
+     * Venue mark price of `symbol` (info `metaAndAssetCtxs` → `markPx`; passes the dex for HIP-3).
+     * Read fresh (never the markets cache, whose markPrice may be an allMids substitute).
+     * Missing / non-positive → PRICE_STALE.
+     */
+    async markPrice(symbol) {
+        const coin = this._venueCoin(symbol);
+        const meta = await this._infoPost(this._dex ? { type: "metaAndAssetCtxs", dex: this._dex } : { type: "metaAndAssetCtxs" });
+        const universe = meta?.[0]?.universe;
+        const idx = Array.isArray(universe) ? universe.findIndex((a) => a?.name === coin) : -1;
+        const raw = idx >= 0 && Array.isArray(meta?.[1]) ? meta[1][idx]?.markPx : undefined;
+        const mark = typeof raw === "string" && raw.trim() !== "" ? Number(raw) : NaN;
+        if (!(mark > 0) || !Number.isFinite(mark)) {
+            throw new PerpError("PRICE_STALE", `Hyperliquid ${symbol.toUpperCase()}${this._dex ? ` (dex ${this._dex})` : ""}: no mark price in metaAndAssetCtxs (got ${JSON.stringify(raw)})`, {
+                exchange: "hyperliquid",
+                remediation: "Retry when the venue publishes a mark price for this market",
+            });
+        }
+        return mark;
+    }
+    /**
+     * Protection price an IOC market order on `symbol` would be sent with now.
+     * Exposed so a TradingV2 wrapper can record execution.{protectionPrice, slippageBps}
+     * (appliedBps = the bound after HL rounding).
+     */
+    async computeProtectionPrice(symbol, side, slippage) {
+        const ref = await this.referencePrice(symbol);
+        const { protectionPrice, appliedBps } = hlProtectionPrice(ref, side, slippage.bps, this.getSzDecimals(symbol), 6);
+        await assertHlAppliedBps(appliedBps, `${symbol.toUpperCase()} protection ${protectionPrice} vs reference ${ref}`);
+        return { referencePrice: String(ref), protectionPrice, appliedBps };
+    }
+    /** Definite IOC outcome of a raw order response (see hlIocOutcome). */
+    iocOutcomeOf(raw) {
+        return hlIocOutcome(raw);
     }
     /**
      * Sign and send any exchange action via raw EIP-712 signing.
@@ -682,85 +1355,129 @@ export class HyperliquidAdapter {
         }
         return result;
     }
-    async _signAndSendAction(action) {
+    /** Monotonic ms nonce: unique even for rapid-fire requests in the same millisecond. */
+    static _nextNonce() {
+        const now = Date.now();
+        HyperliquidAdapter._lastNonce = now > HyperliquidAdapter._lastNonce ? now : HyperliquidAdapter._lastNonce + 1;
+        return HyperliquidAdapter._lastNonce;
+    }
+    get _network() {
+        return this._testnet ? "testnet" : "mainnet";
+    }
+    /**
+     * Sign an L1 action with the active signer tier (agent or master) and POST it.
+     * `nonce` must be passed when the action itself carries it (agentSendAsset).
+     */
+    async _signAndSendAction(action, nonce = HyperliquidAdapter._nextNonce()) {
         const { signer } = this._resolveSigner();
-        const { encode } = await import("@msgpack/msgpack");
-        const { ethers, keccak256 } = await import("ethers");
-        const isMainnet = !this._testnet;
-        const baseUrl = isMainnet
-            ? "https://api.hyperliquid.xyz"
-            : "https://api.hyperliquid-testnet.xyz";
         // Normalize trailing zeros from 'p' and 's' fields before hashing.
         // The HL validator does the same; without this, the hash differs and the
         // recovered signer address is wrong → "User or API Wallet does not exist".
         const normalizedAction = HyperliquidAdapter._normalizeAction(action);
-        // Sign L1 action (replicates SDK's signL1Action)
-        // Monotonic nonce: ensures uniqueness even for rapid-fire requests in same millisecond
-        const now = Date.now();
-        HyperliquidAdapter._lastNonce = now > HyperliquidAdapter._lastNonce ? now : HyperliquidAdapter._lastNonce + 1;
-        const nonce = HyperliquidAdapter._lastNonce;
-        const msgPackBytes = encode(normalizedAction);
-        const data = new Uint8Array(msgPackBytes.length + 9); // +8 nonce +1 vault flag
-        data.set(msgPackBytes);
-        const view = new DataView(data.buffer);
-        view.setBigUint64(msgPackBytes.length, BigInt(nonce), false);
-        view.setUint8(msgPackBytes.length + 8, 0); // no vault
-        const hash = keccak256(data);
-        const phantomDomain = {
-            name: "Exchange",
-            version: "1",
-            chainId: 1337,
-            verifyingContract: "0x0000000000000000000000000000000000000000",
-        };
-        const agentTypes = {
-            Agent: [
-                { name: "source", type: "string" },
-                { name: "connectionId", type: "bytes32" },
-            ],
-        };
-        const phantomAgent = {
-            source: isMainnet ? "a" : "b",
-            connectionId: hash,
-        };
-        const sig = await signer.signTypedData(phantomDomain, agentTypes, phantomAgent);
-        const parsed = ethers.Signature.from(sig);
-        const payload = {
-            action,
-            nonce,
-            signature: { r: parsed.r, s: parsed.s, v: parsed.v },
-            vaultAddress: null,
-        };
-        const res = await fetch(`${baseUrl}/exchange`, {
-            method: "POST",
-            headers: { "Content-Type": "application/json" },
-            body: JSON.stringify(payload),
-        });
-        const text = await res.text();
+        let signature;
+        try {
+            signature = await signHlL1Action(signer, normalizedAction, nonce, !this._testnet);
+        }
+        catch (e) {
+            // Pre-send: nothing reached the venue (definite, never ORDER_PENDING).
+            if (e instanceof PerpError)
+                throw e;
+            throw new PerpError("SIGNATURE_FAILED", `HL ${String(action.type)} action signing failed: ${e instanceof Error ? e.message : String(e)}`, { exchange: "hyperliquid" });
+        }
+        try {
+            return await this._postExchange({ action, nonce, signature, vaultAddress: null });
+        }
+        catch (e) {
+            throw hlL1ActionRejection(String(action.type), e);
+        }
+    }
+    /**
+     * Sign a USER-signed action (HyperliquidSignTransaction EIP-712) with the MASTER
+     * signer and POST it. Agents cannot sign these — no agent fallback: without a
+     * master signer this throws NO_SIGNER_AVAILABLE before anything is sent.
+     */
+    async _signAndSendUserAction(type, fields) {
+        const master = this._evmSigner;
+        if (!master) {
+            throw new PerpError("NO_SIGNER_AVAILABLE", `Hyperliquid ${type} must be signed by the master wallet (an agent wallet cannot sign it), and none is configured`, {
+                exchange: "hyperliquid",
+                remediation: "Run with the master wallet: perp -e hyperliquid --ows <wallet> ... (or export PRIVATE_KEY=0x...)",
+            });
+        }
+        const nonce = HyperliquidAdapter._nextNonce();
+        const action = buildHlUserSignedAction(type, this._network, { ...fields, [hlUserSignedNonceField(type)]: nonce });
+        let signature;
+        try {
+            signature = await signHlUserSignedAction(master, action);
+        }
+        catch (e) {
+            if (e instanceof PerpError)
+                throw e;
+            throw new PerpError("SIGNATURE_FAILED", `HL ${type} signing failed: ${e instanceof Error ? e.message : String(e)}`, { exchange: "hyperliquid" });
+        }
+        // User-signed body: {action, nonce, signature} — no vaultAddress (python SDK _post_action
+        // sends null for these; the venue reads the signer from the EIP-712 signature).
+        try {
+            return await this._postExchange({ action, nonce, signature });
+        }
+        catch (e) {
+            throw hlUserActionRejection(type, e);
+        }
+    }
+    /** POST /exchange request timeout: a request the venue never answers must not hang the CLI. */
+    static EXCHANGE_TIMEOUT_MS = 30_000;
+    /**
+     * POST /exchange; an `err` envelope or a 4xx non-JSON body throws (the venue refused it).
+     * Once the signed action is on the wire its outcome is unknown unless the venue answers:
+     * a connection reset, timeout, 5xx or unreadable 2xx body → ORDER_PENDING (sendFailure),
+     * never a retryable EXCHANGE_UNREACHABLE / TIMEOUT. No connection at all → not sent.
+     */
+    async _postExchange(payload) {
+        const baseUrl = this._testnet ? "https://api.hyperliquid-testnet.xyz" : "https://api.hyperliquid.xyz";
+        const type = String(payload.action?.type);
+        const what = `${type} action`;
+        const remediation = `Do NOT resubmit — the ${type} may have been executed. Check open orders, positions and balances first: perp -e hyperliquid account orders / portfolio`;
+        let res;
+        let text;
+        try {
+            res = await fetch(`${baseUrl}/exchange`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify(payload),
+                signal: AbortSignal.timeout(HyperliquidAdapter.EXCHANGE_TIMEOUT_MS),
+            });
+            text = await res.text();
+        }
+        catch (e) {
+            throw sendFailure("hyperliquid", what, e, remediation);
+        }
+        if (res.status >= 500) {
+            throw orderOutcomeUnknown("hyperliquid", what, new Error(`HTTP ${res.status}: ${text.slice(0, 200)}`), remediation);
+        }
         let result;
         try {
             result = JSON.parse(text);
         }
         catch {
-            throw new Error(`HL exchange API error (${res.status}): ${text.slice(0, 200)}`);
+            if (res.status >= 400)
+                throw new Error(`HL exchange API error (${res.status}): ${text.slice(0, 200)}`);
+            throw orderOutcomeUnknown("hyperliquid", what, new Error(`unreadable response (HTTP ${res.status}): ${text.slice(0, 200)}`), remediation);
         }
         if (result?.status === "err") {
-            throw new Error(typeof result.response === "string" ? result.response : JSON.stringify(result));
+            throw new HlErrResponse(typeof result.response === "string" ? result.response : JSON.stringify(result));
         }
         return result;
     }
-    /**
-     * Place an order via raw exchange API with EIP-712 signing.
-     * This bypasses the SDK's symbolConversion and supports dex-specific orders.
-     */
-    async _rawPlaceOrder(opts) {
-        // Remove trailing zeros (HL API requirement)
+    /** One order wire (HL `order` action entry); p/s trailing zeros removed (HL API requirement). */
+    _orderWire(opts) {
         const trimZeros = (s) => {
             if (!s.includes("."))
                 return s;
             const n = s.replace(/\.?0+$/, "");
             return n === "-0" ? "0" : n;
         };
-        const orderWire = {
+        // No "dex" field needed — the global asset index (110000+) encodes the dex
+        const wire = {
             a: opts.assetIndex,
             b: opts.isBuy,
             p: trimZeros(opts.price),
@@ -768,33 +1485,79 @@ export class HyperliquidAdapter {
             r: opts.reduceOnly,
             t: opts.orderType,
         };
-        const action = {
-            type: "order",
-            orders: [orderWire],
-            grouping: "na",
-        };
-        // No "dex" field needed — the global asset index (110000+) encodes the dex
-        return this._signAndSendAction(action);
+        // `c` last, only when set — the signed msgpack follows key order (python SDK order_request_to_order_wire).
+        if (opts.cloid !== undefined && opts.cloid !== null)
+            wire.c = opts.cloid;
+        return wire;
+    }
+    /**
+     * Place an order via raw exchange API with EIP-712 signing.
+     * This bypasses the SDK's symbolConversion and supports dex-specific orders.
+     */
+    async _rawPlaceOrder(opts) {
+        const result = await this._signAndSendAction(opts.action);
+        this._validateVenueAck(result, "order");
+        return result;
+    }
+    /**
+     * A computed limit price for `symbol` on the HL grid, aligned passively for `side` (buy ↓,
+     * sell ↑). For strategy / grid / slice prices — limitOrder itself refuses off-grid input.
+     */
+    async alignComputedPrice(symbol, side, price) {
+        await this.getAssetIndex(symbol.toUpperCase()); // loads meta (szDecimals) when empty
+        return hlAlignPriceToGrid(price, this.getSzDecimals(symbol), 6, side === "buy" ? "down" : "up");
     }
     async limitOrder(symbol, side, price, size, opts) {
-        // Normalize TIF: accept "IOC"/"GTC"/"ALO" (uppercase) or native "Ioc"/"Gtc"/"Alo"
-        const rawTif = opts?.tif ?? "Gtc";
-        const tifMap = { IOC: "Ioc", GTC: "Gtc", ALO: "Alo" };
-        const tif = (tifMap[rawTif.toUpperCase()] ?? rawTif);
-        const reduceOnly = opts?.reduceOnly ?? false;
-        // Round price/size to HL-supported decimals
-        const szDec = this.getSzDecimals(symbol);
-        const roundedPrice = this._hlRoundPrice(Number(price), szDec);
-        const roundedSize = Number(size).toFixed(szDec);
+        // TIF aliases (§13.3): GTC/IOC/ALO or native spellings; FOK → CAPABILITY_UNSUPPORTED.
+        let action;
+        const cloid = opts?.clientOrderId === undefined ? null : HyperliquidAdapter.requireCloid(opts.clientOrderId);
+        try { // pre-send (see marketOrder)
+            const tif = hlTif(opts?.tif ?? "GTC");
+            const reduceOnly = opts?.reduceOnly ?? false;
+            const assetIndex = await this.getAssetIndex(symbol.toUpperCase()); // loads meta (szDecimals) when empty
+            // Off-grid price → INVALID_TICK (refused, never rounded); size floored to the lot.
+            const szDec = this.getSzDecimals(symbol);
+            const roundedPrice = hlRequirePriceOnGrid(price, szDec, 6, "limit price");
+            const roundedSize = floorSize(size, hlSizeStep(szDec)); // floored to the lot; 0 → SIZE_TOO_SMALL
+            action = await this._orderAction([this._orderWire({
+                    assetIndex,
+                    isBuy: side === "buy",
+                    price: roundedPrice,
+                    size: roundedSize,
+                    orderType: { limit: { tif } },
+                    reduceOnly,
+                    cloid,
+                })], "na", assetIndex);
+        }
+        catch (e) {
+            throw orderNotSent("hyperliquid", `limit ${side} ${size} ${symbol.toUpperCase()} @ ${price}`, e);
+        }
         // Use _rawPlaceOrder for both DEX and non-DEX (SDK exchange.placeOrder is unavailable)
-        const result = await this._rawPlaceOrder({
-            assetIndex: await this.getAssetIndex(symbol.toUpperCase()),
-            isBuy: side === "buy",
-            price: roundedPrice,
-            size: roundedSize,
-            orderType: { limit: { tif } },
-            reduceOnly,
+        const result = await this._rawPlaceOrder({ action });
+        await this._invalidateAccountCache();
+        // The cloid sent rides on the result (`clientOrderId`), like Pacifica's.
+        return cloid !== null ? { ...result, clientOrderId: cloid } : result;
+    }
+    /**
+     * Cancel one order by client order id — exchange-endpoint docs "Cancel order(s) by cloid":
+     * `{ "type": "cancelByCloid", "cancels": [{ "asset": Number, "cloid": String }] }`. The asset is
+     * the global id, so a HIP-3 dex order is addressed the same way. Per-entry error → ORDER_REJECTED.
+     */
+    async cancelByCloid(symbol, cloid) {
+        this.ensureSigner();
+        const id = HyperliquidAdapter.requireCloid(cloid);
+        let assetIndex;
+        try { // pre-send: the `meta` read behind the asset id
+            assetIndex = await this.getAssetIndex(symbol.toUpperCase());
+        }
+        catch (e) {
+            throw orderNotSent("hyperliquid", `cancel c:${id} ${symbol.toUpperCase()}`, e);
+        }
+        const result = await this._signAndSendAction({
+            type: "cancelByCloid",
+            cancels: [{ asset: assetIndex, cloid: id }],
         });
+        this._validateVenueAck(result, `cancel c:${id}`);
         await this._invalidateAccountCache();
         return result;
     }
@@ -805,17 +1568,33 @@ export class HyperliquidAdapter {
         // expose it as a callable method. Use raw cancel action via _signAndSendAction
         // instead — same approach as the HIP-3 dex branch — which works uniformly for
         // standard perps and HIP-3 dexes.
-        const assetIndex = await this.getAssetIndex(symbol.toUpperCase());
+        const oid = this._oidOf(orderId);
+        let assetIndex;
+        try { // pre-send (see marketOrder): the `meta` read behind the asset id
+            assetIndex = await this.getAssetIndex(symbol.toUpperCase());
+        }
+        catch (e) {
+            throw orderNotSent("hyperliquid", `cancel ${orderId} ${symbol.toUpperCase()}`, e);
+        }
         const result = await this._signAndSendAction({
             type: "cancel",
-            cancels: [{ a: assetIndex, o: parseInt(orderId) }],
+            cancels: [{ a: assetIndex, o: oid }],
         });
+        // A refused cancel (already filled, unknown oid) also comes back under an
+        // "ok" envelope — without this the user is told the order was cancelled.
+        this._validateVenueAck(result, `cancel ${orderId}`);
         await this._invalidateAccountCache();
         return result;
     }
     async cancelAllOrders(symbol) {
         this.ensureSigner();
-        const orders = await this.getOpenOrders();
+        let orders;
+        try { // pre-send: the frontendOpenOrders listing — nothing is cancelled when it fails
+            orders = await this.getOpenOrders();
+        }
+        catch (e) {
+            throw orderNotSent("hyperliquid", `cancel-all${symbol ? ` ${symbol.toUpperCase()}` : ""}`, e);
+        }
         const toCancel = symbol
             ? orders.filter((o) => {
                 const norm = (s) => s.toUpperCase().replace(/-PERP$/, "").replace(/^[^:]+:/, "");
@@ -825,35 +1604,150 @@ export class HyperliquidAdapter {
         // Use _signAndSendAction uniformly for both standard perps and HIP-3 dexes.
         // SDK exchange.cancelOrder has the same runtime unavailability as single
         // cancelOrder (see comment there); raw cancel action works for both paths.
+        // Every target is attempted (like lighter.ts cancelAllOrders): one refused / unknown cancel
+        // must not leave the orders after it untouched and unreported. A per-entry "Order was never
+        // placed, already canceled, or filled." means the order is no longer open — reported as gone
+        // (not cancelled by this call), not a failure. All cancelled / gone → the raw results; any
+        // failure → one error carrying the per-order outcome.
         const results = [];
+        const perOrder = [];
         for (const o of toCancel) {
-            const assetIndex = await this.getAssetIndex(o.symbol);
-            results.push(await this._signAndSendAction({
-                type: "cancel",
-                cancels: [{ a: assetIndex, o: parseInt(o.orderId) }],
-            }));
+            try {
+                const oid = this._oidOf(o.orderId);
+                let assetIndex;
+                try { // pre-send: the `meta` read behind the asset id
+                    assetIndex = await this.getAssetIndex(o.symbol);
+                }
+                catch (e) {
+                    throw orderNotSent("hyperliquid", `cancel ${o.orderId} ${o.symbol}`, e);
+                }
+                const res = await this._signAndSendAction({
+                    type: "cancel",
+                    cancels: [{ a: assetIndex, o: oid }],
+                });
+                this._validateVenueAck(res, `cancel ${o.orderId}`);
+                results.push(res);
+                perOrder.push({ orderId: o.orderId, symbol: o.symbol, outcome: "cancelled", code: null, error: null });
+            }
+            catch (e) {
+                const venueErrors = e instanceof PerpError ? e.structured.details?.venueErrors : undefined;
+                const gone = Array.isArray(venueErrors) && venueErrors.length > 0
+                    && venueErrors.every(v => typeof v === "string" && /already canceled, or filled/i.test(v));
+                perOrder.push({ orderId: o.orderId, symbol: o.symbol, outcome: gone ? "gone" : "failed", code: classifyError(e, "hyperliquid").code, error: extractErrorMessage(e) });
+            }
         }
-        return results;
+        const failed = perOrder.filter(r => r.outcome === "failed");
+        const gone = perOrder.filter(r => r.outcome === "gone");
+        if (failed.length === 0) {
+            if (gone.length > 0) {
+                console.error(`[hyperliquid] cancel-all: ${gone.length} order(s) were no longer open (already cancelled or filled, not cancelled by this call): ${gone.map(r => r.orderId).join(", ")}`);
+            }
+            return results;
+        }
+        const cancelled = perOrder.filter(r => r.outcome === "cancelled").length;
+        // Some cancelled → ORDER_PARTIAL; none cancelled → ORDER_REJECTED only when every failure is a
+        // definite refusal, otherwise the outcome of at least one cancel is unknown (ORDER_PENDING).
+        const code = cancelled > 0 ? "ORDER_PARTIAL"
+            : failed.every(r => r.code !== null && DEFINITE_ORDER_FAILURE_CODES.has(r.code)) ? "ORDER_REJECTED" : "ORDER_PENDING";
+        throw new PerpError(code, `hyperliquid cancel-all: ${cancelled} of ${perOrder.length} order(s) cancelled${gone.length > 0 ? `, ${gone.length} already gone (cancelled or filled)` : ""}; failed: ${failed.map(r => `${r.orderId} ${r.symbol} (${r.error})`).join("; ")}`, {
+            exchange: "hyperliquid",
+            results: perOrder,
+            remediation: "Check which orders are still open (perp account orders -e hyperliquid) and cancel the remaining ones individually",
+        });
     }
     // ── Interface methods ──
+    /**
+     * Amend (design §13.4, §13.10 #10) via HL native batchModify. `size` = the NEW
+     * open (unfilled) size — native-modify semantics, not the original total. The
+     * order's own tif (Gtc/Alo) and reduceOnly are read from frontendOpenOrders
+     * and preserved; nothing is hardcoded.
+     */
     async editOrder(symbol, orderId, price, size) {
-        // Look up the existing order's side to preserve it (avoid flipping buy↔sell)
-        const openOrders = await this.getOpenOrders();
-        const existing = openOrders.find(o => o.orderId === orderId);
-        const side = existing?.side ?? "buy";
-        return this.modifyOrder(symbol, parseInt(orderId), side, price, size);
+        // Read the RAW order: the mapped getOpenOrders() hardcodes type:"limit" and
+        // drops reduceOnly, so it cannot distinguish a trigger order from a plain
+        // limit nor preserve reduce-only across the modify.
+        let raw;
+        try { // pre-send (see marketOrder): the order's own attributes
+            raw = await this._infoPost({
+                type: "frontendOpenOrders",
+                user: this._address,
+                ...(this._dex ? { dex: this._dex } : {}),
+            });
+        }
+        catch (e) {
+            throw orderNotSent("hyperliquid", `edit ${orderId} ${symbol.toUpperCase()}`, e);
+        }
+        const existing = (raw ?? []).find(o => String(o.oid ?? "") === orderId);
+        if (!existing) {
+            // Rule #2: never default the side. Guessing "buy" on a resting sell order
+            // rewrites it to the opposite side, which can open or flip a position.
+            throw new PerpError("ORDER_NOT_FOUND", `Hyperliquid order ${orderId} is not among the open orders; refusing to edit (cannot guess its side).`, { exchange: "hyperliquid" });
+        }
+        // L11: the order id must belong to `symbol` — a modify carries the asset index of
+        // `symbol`, so a mismatched id would move another market's order onto this one.
+        const coinNorm = (s) => s.toUpperCase().replace(/-PERP$/, "");
+        const coin = String(existing.coin ?? "");
+        const base = (s) => coinNorm(s.includes(":") ? s.split(":")[1] : s);
+        // HIP-3 coins are "<dex>:<BASE>" (the query above is already scoped to this adapter's dex).
+        const sameCoin = coinNorm(coin) === coinNorm(symbol) || coinNorm(coin) === coinNorm(this.resolveSymbol(symbol))
+            || (coin.includes(":") && !symbol.includes(":") && base(coin) === base(symbol));
+        if (!sameCoin) {
+            throw new PerpError("INVALID_PARAMS", `Hyperliquid order ${orderId} is on ${coin || "an unknown market"}, not ${symbol.toUpperCase()}; refusing to edit`, {
+                exchange: "hyperliquid",
+                remediation: `Pass the order's own symbol: perp trade edit ${coin || "<symbol>"} ${orderId} ...`,
+            });
+        }
+        if (existing.isTrigger === true) {
+            // batchModify is sent without the `a` (always_place) flag. Per the exchange
+            // docs, that path requires a NON-trigger order, so the venue rejects a
+            // modify into a stop/TP — re-placing it as a plain limit would also drop
+            // the trigger. Refuse rather than corrupt the order's semantics.
+            throw new PerpError("INVALID_PARAMS", `Hyperliquid editOrder only supports non-trigger orders (order ${orderId} is ${String(existing.orderType ?? "a trigger order")}). Cancel and re-place it explicitly.`, { exchange: "hyperliquid" });
+        }
+        const sideRaw = String(existing.side);
+        const side = sideRaw === "B" ? "buy" : sideRaw === "A" ? "sell" : sideRaw.toLowerCase();
+        if (side !== "buy" && side !== "sell") {
+            throw new PerpError("EXCHANGE_ERROR", `Hyperliquid order ${orderId} has an unrecognized side "${sideRaw}"; refusing to edit.`, { exchange: "hyperliquid" });
+        }
+        const reduceOnly = existing.reduceOnly === true;
+        const tif = existing.tif;
+        if (tif !== "Gtc" && tif !== "Alo" && tif !== "Ioc") {
+            // Rule #2: never guess the time-in-force (re-placing an ALO as GTC can take liquidity).
+            throw unsupported("Hyperliquid", "amend", `original order attributes unknown (order ${orderId} reports tif ${JSON.stringify(tif ?? null)})`, `Cancel order ${orderId} and place a new order with an explicit --tif`);
+        }
+        // Keep the order's cloid across the modify (the modify carries a full order wire; without
+        // `c` the edited order would lose the id `trade status/cancel c:<cloid>` address it by).
+        const cloid = typeof existing.cloid === "string" && HL_CLOID_RE.test(existing.cloid) ? existing.cloid : null;
+        return this.modifyOrder(symbol, parseInt(orderId), side, price, size, { reduceOnly, tif, ...(cloid !== null ? { cloid } : {}) });
     }
     async setLeverage(symbol, leverage, marginMode = "cross") {
         return this.updateLeverage(symbol, leverage, marginMode === "cross");
     }
     async stopOrder(symbol, side, size, triggerPrice, opts) {
-        return this.triggerOrder(symbol, side, size, triggerPrice, "sl", {
+        // TP vs SL from the trigger vs the MARK price — HL docs: "The mark price is used to trigger
+        // TP/SL orders." Buy at/above or sell at/below the mark = stop (sl); the other side =
+        // take-profit (tp). A wrong tpsl would make the venue trigger the order immediately.
+        // No mark price → PRICE_STALE.
+        const trigger = Number(triggerPrice);
+        if (!(trigger > 0) || !Number.isFinite(trigger)) {
+            throw new PerpError("INVALID_PARAMS", `Invalid trigger price "${triggerPrice}" for ${symbol.toUpperCase()} stop order`, { exchange: "hyperliquid" });
+        }
+        let mark;
+        try { // pre-send (see marketOrder): the metaAndAssetCtxs mark-price read
+            mark = await this.markPrice(symbol);
+        }
+        catch (e) {
+            throw orderNotSent("hyperliquid", `stop ${side} ${size} ${symbol.toUpperCase()} @ ${triggerPrice}`, e);
+        }
+        const tpsl = hlTriggerKind(side, trigger, mark);
+        return this.triggerOrder(symbol, side, size, triggerPrice, tpsl, {
             isMarket: !opts?.limitPrice,
+            limitPrice: opts?.limitPrice,
             reduceOnly: opts?.reduceOnly ?? true,
         });
     }
     async getRecentTrades(symbol, limit = 20) {
-        const trades = await this._infoPost({ type: "recentTrades", coin: symbol.toUpperCase() });
+        const trades = await this._infoPost({ type: "recentTrades", coin: this._venueCoin(symbol) });
         return (trades ?? [])
             .slice(0, limit)
             .map((t) => ({
@@ -866,7 +1760,10 @@ export class HyperliquidAdapter {
         }));
     }
     async getKlines(symbol, interval, startTime, endTime) {
-        const candles = await this.client.info.getCandleSnapshot(symbol.toUpperCase(), interval, startTime, endTime);
+        const candles = await this._infoPost({
+            type: "candleSnapshot",
+            req: { coin: this._venueCoin(symbol), interval, startTime, endTime },
+        });
         return (candles ?? []).map((c) => ({
             time: Number(c.t ?? 0),
             open: String(c.o ?? "0"),
@@ -879,27 +1776,26 @@ export class HyperliquidAdapter {
     }
     async getOrderHistory(limit = 30) {
         this.ensureAddress();
-        const fills = await this.client.info.getUserFills(this._address);
+        const fills = await this._infoPost({ type: "userFills", user: this._address });
         return (fills ?? []).slice(0, limit).map((f) => ({
             orderId: String(f.oid ?? ""),
-            symbol: String(f.coin ?? ""),
-            // SDK convertSymbolsInObject already converts "B"→"buy", "A"→"sell"
-            side: String(f.side) === "B" ? "buy" : String(f.side) === "A" ? "sell" : f.side,
+            symbol: this._displaySymbol(String(f.coin ?? "")),
+            side: String(f.side) === "B" ? "buy" : String(f.side) === "A" ? "sell" : String(f.side).toLowerCase(),
             price: String(f.px ?? "0"),
             size: String(f.sz ?? ""),
             filled: String(f.sz ?? ""),
             status: "filled",
             type: String(f.dir ?? ""),
+            triggerPrice: null, // fills carry no trigger price
         }));
     }
     async getTradeHistory(limit = 30) {
         this.ensureAddress();
-        const fills = await this.client.info.getUserFills(this._address);
+        const fills = await this._infoPost({ type: "userFills", user: this._address });
         return (fills ?? []).slice(0, limit).map((f) => ({
             time: Number(f.time ?? 0),
-            symbol: String(f.coin ?? ""),
-            // SDK convertSymbolsInObject already converts "B"→"buy", "A"→"sell"
-            side: String(f.side) === "B" ? "buy" : String(f.side) === "A" ? "sell" : f.side,
+            symbol: this._displaySymbol(String(f.coin ?? "")),
+            side: String(f.side) === "B" ? "buy" : String(f.side) === "A" ? "sell" : String(f.side).toLowerCase(),
             price: String(f.px ?? "0"),
             size: String(f.sz ?? ""),
             fee: String(f.fee ?? "0"),
@@ -923,10 +1819,10 @@ export class HyperliquidAdapter {
     }
     async getFundingHistory(symbol, limit = 10) {
         const now = Date.now();
-        const history = await this.client.info.perpetuals.getFundingHistory(symbol.toUpperCase(), now - 24 * 60 * 60 * 1000);
+        const history = await this._infoPost({ type: "fundingHistory", coin: this._venueCoin(symbol), startTime: now - 24 * 60 * 60 * 1000 });
         return (history ?? []).slice(-limit).map((h) => ({
             time: Number(h.time ?? 0),
-            rate: String(h.fundingRate ?? "0"),
+            rate: venueRateField(h.fundingRate, "fundingHistory fundingRate", "hyperliquid"),
             price: null,
         }));
     }
@@ -936,13 +1832,50 @@ export class HyperliquidAdapter {
     /**
      * Place a trigger order (stop loss / take profit).
      * Python SDK: order() with trigger type {"trigger": {triggerPx, isMarket, tpsl: "tp"|"sl"}}
+     *
+     * Pricing (design §13.10 #3):
+     * - isMarket (default): HL native market trigger; `p` = trigger ± 10 % (the venue's documented
+     *   market TP/SL slippage tolerance, HL_MARKET_TPSL_SLIPPAGE_BPS), aligned toward crossing.
+     * - limit trigger with an explicit `limitPrice`: that price, rounded to HL's grid.
+     * - limit trigger without `limitPrice`: protection = TRIGGER price ± opts.slippage.bps
+     *   (reference = trigger, not mark), aligned toward crossing. Missing slippage →
+     *   INVALID_PARAMS (no implicit zero-slippage limit at the trigger).
      */
     async triggerOrder(symbol, side, size, triggerPrice, tpsl, opts) {
         this.ensureSigner();
-        const assetIndex = await this.getAssetIndex(symbol.toUpperCase());
+        const what = `${tpsl} trigger ${side} ${size} ${symbol.toUpperCase()} @ ${triggerPrice}`;
+        let assetIndex;
+        try { // pre-send (see marketOrder)
+            assetIndex = await this.getAssetIndex(symbol.toUpperCase());
+        }
+        catch (e) {
+            throw orderNotSent("hyperliquid", what, e);
+        }
         const szDec = this.getSzDecimals(symbol);
-        const roundedSize = Number(size).toFixed(szDec);
-        const roundedTrigger = this._hlRoundPrice(Number(triggerPrice), szDec);
+        const roundedSize = floorSize(size, hlSizeStep(szDec)); // floored to the lot; 0 → SIZE_TOO_SMALL
+        // User-supplied trigger / limit prices: off-grid → INVALID_TICK (never rounded).
+        const roundedTrigger = hlRequirePriceOnGrid(triggerPrice, szDec, 6, "trigger price");
+        // Stop-limit / TP-limit: the order's limit price is the caller's limitPrice, not the trigger.
+        const isMarket = opts?.isMarket ?? true;
+        let roundedLimit;
+        if (opts?.limitPrice !== undefined) {
+            roundedLimit = hlRequirePriceOnGrid(opts.limitPrice, szDec, 6, "trigger limit price");
+        }
+        else if (isMarket) {
+            // Market trigger: `p` = trigger ± the venue's documented market TP/SL tolerance (never the
+            // trigger itself — see HL_MARKET_TPSL_SLIPPAGE_BPS), aligned toward crossing.
+            roundedLimit = hlProtectionPrice(Number(roundedTrigger), side, HL_MARKET_TPSL_SLIPPAGE_BPS, szDec, 6).protectionPrice;
+        }
+        else {
+            if (!opts?.slippage) {
+                throw new PerpError("INVALID_PARAMS", `Limit trigger order for ${symbol.toUpperCase()} needs a limit price or a resolved slippage bound`, {
+                    remediation: "Pass --limit-price, or use a market trigger.",
+                });
+            }
+            const pp = hlProtectionPrice(Number(roundedTrigger), side, opts.slippage.bps, szDec, 6);
+            await assertHlAppliedBps(pp.appliedBps, `${symbol.toUpperCase()} trigger limit ${pp.protectionPrice} vs trigger ${roundedTrigger}`);
+            roundedLimit = pp.protectionPrice;
+        }
         // Remove trailing zeros (HL API requirement)
         const trimZeros = (s) => {
             if (!s.includes("."))
@@ -953,23 +1886,90 @@ export class HyperliquidAdapter {
         const orderWire = {
             a: assetIndex,
             b: side === "buy",
-            p: trimZeros(roundedTrigger),
+            p: trimZeros(roundedLimit),
             s: trimZeros(roundedSize),
             r: opts?.reduceOnly ?? true,
             t: {
                 trigger: {
-                    isMarket: opts?.isMarket ?? true,
+                    isMarket,
                     triggerPx: trimZeros(roundedTrigger),
                     tpsl,
                 },
             },
         };
-        const action = {
-            type: "order",
-            orders: [orderWire],
-            grouping: opts?.grouping ?? "positionTpsl",
-        };
-        return this._signAndSendAction(action);
+        let action;
+        try { // pre-send: the builder approval read (info maxBuilderFee) when a builder fee is configured
+            action = await this._orderAction([orderWire], opts?.grouping ?? "positionTpsl", assetIndex);
+        }
+        catch (e) {
+            throw orderNotSent("hyperliquid", what, e);
+        }
+        // The trigger ack is the bare status "waitingForTrigger" (no oid): the open trigger orders are
+        // read before and after so the new order's oid can be identified (_newTriggerOid).
+        let coin = "";
+        let before = null;
+        try {
+            coin = this._venueCoin(symbol);
+            before = await this._triggerOids(coin);
+        }
+        catch (e) {
+            // Only the oid lookup is skipped (the order is still sent); the result then carries no id.
+            console.error(`[hyperliquid] Warning: open-orders read before the trigger order failed (${e instanceof Error ? e.message : String(e)}) — its order id will not be resolved`);
+        }
+        const result = await this._signAndSendAction(action);
+        this._validateVenueAck(result, `${tpsl.toUpperCase()} trigger order for ${symbol.toUpperCase()}`);
+        const statuses = result?.response?.data?.statuses;
+        if (before === null || !Array.isArray(statuses) || statuses[0] !== "waitingForTrigger")
+            return result;
+        const triggerOid = await this._newTriggerOid(coin, before, {
+            side: orderWire.b ? "B" : "A", triggerPx: orderWire.t.trigger.triggerPx, sz: orderWire.s, reduceOnly: orderWire.r,
+        });
+        if (triggerOid === null) {
+            console.error(`[hyperliquid] Warning: ${tpsl.toUpperCase()} trigger order for ${symbol.toUpperCase()} placed, but its order id could not be identified — find it with: perp account orders -e hyperliquid`);
+            return result;
+        }
+        return { ...result, triggerOid };
+    }
+    /** Open trigger orders of `coin` (frontendOpenOrders rows with isTrigger), by oid. */
+    async _triggerOids(coin) {
+        const req = { type: "frontendOpenOrders", user: this._address };
+        if (this._dex)
+            req.dex = this._dex;
+        const rows = await this._infoPost(req);
+        if (!Array.isArray(rows))
+            throw new PerpError("EXCHANGE_ERROR", "frontendOpenOrders returned no array", { exchange: "hyperliquid" });
+        return new Set(rows.filter(r => r.coin === coin && r.isTrigger === true).map(r => String(r.oid)));
+    }
+    /**
+     * The oid of the trigger order just placed: the single open trigger order of `coin` not listed
+     * before, with the side / trigger price / size / reduce-only sent. Several reads (500 ms apart);
+     * none or more than one candidate → null (never guessed).
+     */
+    async _newTriggerOid(coin, before, sent) {
+        for (let attempt = 0; attempt < 4; attempt++) {
+            if (attempt > 0)
+                await new Promise(r => setTimeout(r, 500));
+            const req = { type: "frontendOpenOrders", user: this._address };
+            if (this._dex)
+                req.dex = this._dex;
+            let rows;
+            try {
+                rows = await this._infoPost(req);
+            }
+            catch {
+                continue;
+            }
+            if (!Array.isArray(rows))
+                continue;
+            const hits = rows.filter(r => r.coin === coin && r.isTrigger === true && !before.has(String(r.oid)) && r.side === sent.side
+                && Number(r.triggerPx) === Number(sent.triggerPx) && Number(r.sz) === Number(sent.sz) && r.reduceOnly === sent.reduceOnly
+                && typeof r.oid === "number" && Number.isSafeInteger(r.oid));
+            if (hits.length === 1)
+                return String(hits[0].oid);
+            if (hits.length > 1)
+                return null;
+        }
+        return null;
     }
     /**
      * Place a TWAP order.
@@ -978,6 +1978,7 @@ export class HyperliquidAdapter {
      */
     async twapOrder(symbol, side, size, durationMinutes, opts) {
         const assetIndex = await this.getAssetIndex(symbol);
+        hlAssertTwapBounds(symbol, size, durationMinutes, await this.markPrice(symbol));
         const action = {
             type: "twapOrder",
             twap: {
@@ -989,7 +1990,9 @@ export class HyperliquidAdapter {
                 t: opts?.randomize ?? true,
             },
         };
-        return this._sendExchangeAction(action);
+        const result = await this._sendExchangeAction(action);
+        hlValidateTwapResult(result, `TWAP ${side} ${size} ${symbol}`);
+        return result;
     }
     /**
      * Cancel a TWAP order.
@@ -1001,53 +2004,129 @@ export class HyperliquidAdapter {
             a: assetIndex,
             t: twapId,
         };
-        return this._sendExchangeAction(action);
+        const result = await this._sendExchangeAction(action);
+        hlValidateTwapResult(result, `TWAP cancel ${twapId}`);
+        return result;
+    }
+    /** Venue margin restriction of `symbol` (meta marginMode / onlyIsolated); null = unrestricted. */
+    marginModeOf(symbol) {
+        return this._marginModeMap.get(this.resolveSymbol(symbol.toUpperCase())) ?? null;
     }
     /**
-     * Update leverage for a symbol.
-     * Uses SDK's built-in updateLeverage method.
+     * Update leverage for a symbol — L1 action `updateLeverage` (agent-signable),
+     * python SDK update_leverage. Cross is refused up front on isolated-only assets.
      */
     async updateLeverage(symbol, leverage, isCross = true) {
         this.ensureSigner();
-        return this.sdk.exchange.updateLeverage(this.resolveSymbol(symbol), isCross ? "cross" : "isolated", leverage);
+        let asset;
+        try { // pre-send (see marketOrder): the leverage change was not sent
+            asset = await this.getAssetIndex(symbol.toUpperCase());
+        }
+        catch (e) {
+            throw orderNotSent("hyperliquid", `leverage ${leverage}x ${symbol.toUpperCase()}`, e);
+        }
+        if (!Number.isInteger(leverage) || leverage < 1) {
+            throw new PerpError("INVALID_PARAMS", `Hyperliquid leverage must be a positive integer (got ${leverage})`, { exchange: "hyperliquid" });
+        }
+        const mm = this.marginModeOf(symbol);
+        if (isCross && mm !== null) {
+            throw unsupported("Hyperliquid", "cross margin", `${symbol.toUpperCase()} is isolated-only on the venue (marginMode ${mm})`, "Use --isolated for this market");
+        }
+        return this._signAndSendAction({ type: "updateLeverage", asset, isCross, leverage });
     }
     /**
-     * Update isolated margin for a position.
-     * amount > 0 to add margin, amount < 0 to remove
+     * Add (amount > 0) or remove (amount < 0) isolated margin — L1 action
+     * `updateIsolatedMargin`, python SDK update_isolated_margin: `isBuy` is always
+     * true and the SIGNED `ntli` (USDC × 1e6) carries the direction.
      */
     async updateIsolatedMargin(symbol, amount) {
         this.ensureSigner();
-        return this.sdk.exchange.updateIsolatedMargin(this.resolveSymbol(symbol), amount > 0, Math.round(Math.abs(amount) * 1e6));
+        const ntli = Math.round(amount * 1e6);
+        if (!Number.isFinite(amount) || ntli === 0) {
+            throw new PerpError("INVALID_PARAMS", `Hyperliquid isolated margin change must be a non-zero USDC amount (got ${amount})`, { exchange: "hyperliquid" });
+        }
+        const asset = await this.getAssetIndex(symbol.toUpperCase());
+        if (ntli < 0 && this.marginModeOf(symbol) === "strictIsolated") {
+            throw unsupported("Hyperliquid", "isolated margin removal", `${symbol.toUpperCase()} is strictIsolated on the venue (margin cannot be removed)`, "Close or reduce the position to release margin");
+        }
+        return this._signAndSendAction({ type: "updateIsolatedMargin", asset, isBuy: true, ntli });
     }
     /**
-     * Withdraw from Hyperliquid L1 bridge.
-     * Python SDK: withdraw_from_bridge(amount, destination) → action type "withdraw3"
+     * Withdraw USDC over CCTP (native USDC) — user-signed `sendToEvmWithData` (master only):
+     * HyperCore is debited, the USDC is burned on HyperEVM and CCTP mints it on `chain`
+     * (default Arbitrum). The Arbitrum Bridge2 `withdraw3` path is no longer used.
+     * Docs: developers.circle.com/cctp/howtos/withdraw-usdc-from-hypercore-to-evm —
+     * sourceDex "spot" (unified accounts hold USDC in spot) or "" (standard accounts' perp
+     * balance); data "0x" = automatic forwarding, which CCTP charges a fixed fee for
+     * (Arbitrum 0.2 USDC; an amount below the fee reverts).
      */
-    async withdraw(amount, destination, _opts) {
-        this.ensureSigner();
-        try {
-            return await this.sdk.exchange.initiateWithdrawal(destination, parseFloat(amount));
+    async withdraw(amount, destination, opts) {
+        if (opts?.assetId !== undefined || opts?.routeType !== undefined) {
+            throw new PerpError("INVALID_PARAMS", "Hyperliquid withdraw takes no assetId / routeType (USDC over CCTP; pick the destination with --chain)", { exchange: "hyperliquid" });
         }
-        catch {
-            // Fallback: try raw action if SDK method signature changed
-            const action = {
-                type: "withdraw3",
-                hyperliquidChain: this._testnet ? "Testnet" : "Mainnet",
-                signatureChainId: this._testnet ? "0x66eee" : "0xa4b1",
-                destination,
-                amount,
-                time: Date.now(),
-            };
-            return this._sendExchangeAction(action);
+        const chain = opts?.chain ?? "arbitrum";
+        const route = HL_CCTP_ROUTES[chain];
+        const amountStr = hlAmountString(amount);
+        if (route.forwardingFeeUsdc !== null && !(Number(amountStr) > Number(route.forwardingFeeUsdc))) {
+            throw new PerpError("SIZE_TOO_SMALL", `Hyperliquid CCTP withdraw ${amountStr} USDC does not exceed the ${chain} forwarding fee ${route.forwardingFeeUsdc} USDC (the transfer would revert); nothing was sent`, { exchange: "hyperliquid" });
         }
+        return this._signAndSendUserAction("sendToEvmWithData", {
+            token: "USDC",
+            amount: amountStr,
+            sourceDex: this.isUnifiedAccount ? "spot" : "",
+            destinationRecipient: hlDestination(destination),
+            addressEncoding: "hex",
+            destinationChainId: route.cctpDomain,
+            gasLimit: 200000,
+            data: "0x",
+        });
     }
     /**
-     * Transfer USD between accounts on Hyperliquid L1.
-     * Python SDK: usd_transfer(amount, destination)
+     * Send USDC to another Hyperliquid account — user-signed `usdSend` (master only),
+     * python SDK usd_transfer.
      */
     async usdTransfer(amount, destination) {
+        return this._signAndSendUserAction("usdSend", { destination: hlDestination(destination), amount: hlAmountString(String(amount)) });
+    }
+    /**
+     * Move USDC between this account's spot and perp balances — user-signed
+     * `usdClassTransfer` (master only), python SDK usd_class_transfer.
+     */
+    async usdClassTransfer(amount, toPerp) {
+        return this._signAndSendUserAction("usdClassTransfer", { amount: hlAmountString(amount), toPerp });
+    }
+    /**
+     * Move this dex's collateral token between spot and this adapter's perp dex as an
+     * L1 action `agentSendAsset` (agent-signable; destination = own account). Spot →
+     * perp when `toPerp`, else perp → spot. The token is "<name>:<tokenId>" of the
+     * dex collateral token, read from spotMeta (never hardcoded).
+     */
+    async agentSendAsset(amount, toPerp) {
         this.ensureSigner();
-        return this.sdk.exchange.usdTransfer(destination, amount);
+        this.ensureAddress();
+        const token = await this._collateralTokenWire();
+        const nonce = HyperliquidAdapter._nextNonce();
+        const action = {
+            type: "agentSendAsset",
+            destination: this._address.toLowerCase(),
+            sourceDex: toPerp ? "spot" : this._dex,
+            destinationDex: toPerp ? this._dex : "spot",
+            token,
+            amount: hlAmountString(amount),
+            fromSubAccount: "",
+            nonce,
+        };
+        return this._signAndSendAction(action, nonce);
+    }
+    /** "<name>:<tokenId>" of this dex's collateral token (meta{dex}.collateralToken → spotMeta tokens). */
+    async _collateralTokenWire() {
+        const idx = await this._getCollateralToken();
+        const spotMeta = await this._infoPost({ type: "spotMeta" });
+        const t = (spotMeta?.tokens ?? []).find((x) => x.index === idx);
+        if (!t || typeof t.name !== "string" || typeof t.tokenId !== "string" || !/^0x[0-9a-fA-F]+$/.test(t.tokenId)) {
+            throw new PerpError("EXCHANGE_ERROR", `Hyperliquid spotMeta has no token id for collateral token index ${idx}`, { exchange: "hyperliquid" });
+        }
+        return `${t.name}:${t.tokenId}`;
     }
     /**
      * Create a sub-account.
@@ -1072,10 +2151,18 @@ export class HyperliquidAdapter {
         return this._sendExchangeAction(action);
     }
     /**
-     * Modify an existing order.
+     * Modify an existing order (native batchModify). `newSize` = new open size.
+     * `tif`/`reduceOnly` must be the original order's (editOrder reads them from
+     * frontendOpenOrders) — a modify otherwise silently changes the order's TIF.
      */
     async modifyOrder(symbol, orderId, newSide, newPrice, newSize, opts) {
-        const assetIndex = await this.getAssetIndex(symbol);
+        let assetIndex;
+        try { // pre-send (see marketOrder)
+            assetIndex = await this.getAssetIndex(symbol);
+        }
+        catch (e) {
+            throw orderNotSent("hyperliquid", `modify ${orderId} ${symbol.toUpperCase()}`, e);
+        }
         const szDec = this.getSzDecimals(symbol);
         // Remove trailing zeros (HL API requirement)
         const trimZeros = (s) => {
@@ -1091,41 +2178,87 @@ export class HyperliquidAdapter {
                     order: {
                         a: assetIndex,
                         b: newSide === "buy",
-                        p: trimZeros(this._hlRoundPrice(Number(newPrice), szDec)),
-                        s: trimZeros(Number(newSize).toFixed(szDec)),
-                        r: opts?.reduceOnly ?? false,
-                        t: { limit: { tif: "Gtc" } },
+                        p: trimZeros(hlRequirePriceOnGrid(newPrice, szDec, 6, "modify price")),
+                        s: trimZeros(floorSize(newSize, hlSizeStep(szDec))), // floored to the lot; 0 → SIZE_TOO_SMALL
+                        r: opts.reduceOnly,
+                        t: { limit: { tif: opts.tif } },
+                        ...(opts.cloid !== undefined && opts.cloid !== null ? { c: opts.cloid } : {}),
                     },
                 }],
         };
-        return this._signAndSendAction(action);
+        const result = await this._signAndSendAction(action);
+        this._validateModifyResult(result, orderId);
+        return result;
+    }
+    /**
+     * Validate that the venue actually accepted an order/cancel/modify action.
+     *
+     * HL returns the envelope `status: "ok"` even when the individual entry was
+     * rejected — the real verdict is per-entry in `response.data.statuses[]`,
+     * where an accepted entry is `{filled}` / `{resting}` / the string "success"
+     * and a rejected one is `{error: "..."}`. `_signAndSendAction` only throws on
+     * the ENVELOPE, so every path that skipped this check reported a rejection to
+     * the user as a green success.
+     * A per-entry `{error}` is the venue's definite verdict on that entry — including an
+     * IOC's "could not immediately match" (cancelled with nothing filled) — so it is
+     * ORDER_REJECTED (definite, never quarantined as an unknown outcome).
+     * Also used by HyperliquidSpotAdapter (spot limit orders).
+     */
+    _validateVenueAck(result, what) {
+        const r = result;
+        const statuses = r?.response?.data?.statuses;
+        if (!Array.isArray(statuses) || statuses.length === 0) {
+            // The signed action was already accepted by the envelope: without a per-entry verdict the
+            // order / modify / cancel may or may not have taken effect (like marketOrder's
+            // _validateOrderFill) — ORDER_PENDING, never the retryable EXCHANGE_ERROR.
+            throw orderOutcomeUnknown("hyperliquid", what, new Error("no order status in response"), /^cancel/i.test(what)
+                ? `Do NOT assume the order was cancelled (nor resubmit the cancel blindly) — check open orders first: perp -e hyperliquid account orders`
+                : `Do NOT resubmit — the ${what} may have taken effect. Check open orders and positions first: perp -e hyperliquid account orders / portfolio`);
+        }
+        const errors = statuses
+            .map((s) => (s && typeof s === "object" ? s.error : undefined))
+            .filter((e) => typeof e === "string" && e.length > 0);
+        if (errors.length > 0) {
+            const noMatch = errors.some(e => /could not immediately match/i.test(e));
+            throw new PerpError("ORDER_REJECTED", `Hyperliquid ${what} rejected: ${errors.join("; ")}${noMatch ? " (IOC cancelled by the venue — nothing filled)" : ""}`, { exchange: "hyperliquid", venueErrors: errors });
+        }
+    }
+    _validateModifyResult(result, orderId) {
+        this._validateVenueAck(result, `modify ${orderId}`);
     }
     /**
      * Schedule cancel: cancel all orders at a future time.
      * Max 10 triggers per day.
      */
     async scheduleCancel(timeMs) {
-        const action = {
-            type: "scheduleCancel",
-            time: timeMs,
-        };
+        // Official python SDK schedule_cancel: the action is {"type": "scheduleCancel"} and
+        // `if time is not None: schedule_cancel_action["time"] = time` — when unsetting, the
+        // `time` key is absent from BOTH the signed (msgpack) action and the posted JSON.
+        const action = { type: "scheduleCancel" };
+        if (timeMs !== undefined)
+            action.time = timeMs;
         return this._sendExchangeAction(action);
     }
     /**
-     * Set referral code. Silent — does not throw.
+     * Set the account's referrer (one HL `setReferrer` action, signed + sent).
+     * Called only from the explicit `wallet manage referral set` command — never on
+     * adapter creation. Throws on a venue rejection (SSOT Rule #2).
      */
-    async autoSetReferrer(code) {
-        const referralCode = code || process.env.HL_REFERRAL_CODE || "HYPERCASH";
-        try {
-            const exchange = this.sdk.exchange;
-            if (typeof exchange.setReferrer === "function") {
-                await exchange.setReferrer(referralCode);
-                return;
-            }
+    async setReferrer(code) {
+        if (!code) {
+            throw new PerpError("INVALID_PARAMS", "Hyperliquid referral code is empty", {
+                remediation: "Pass a code: perp -e hyperliquid wallet manage referral set <code>",
+            });
         }
-        catch {
-            // Already referred or method not available — both OK
+        const res = await this._sendExchangeAction({ type: "setReferrer", code });
+        const r = res;
+        if (r && r.status === "err") {
+            throw new PerpError("EXCHANGE_ERROR", `Hyperliquid setReferrer rejected: ${String(r.response)}`, {
+                exchange: "hyperliquid",
+                remediation: "A Hyperliquid account can set a referrer only once; the venue message above says why it was rejected",
+            });
         }
+        return res;
     }
     /**
      * Get funding history for a symbol.
@@ -1189,8 +2322,11 @@ export class HyperliquidAdapter {
     /**
      * Query a specific order by OID.
      */
+    /** info `orderStatus`: `oid` "Either u64 representing the order id or 16-byte hex string representing the client order id". */
     async queryOrder(orderId) {
         this.ensureAddress();
+        if (typeof orderId === "string")
+            HyperliquidAdapter.requireCloid(orderId);
         const baseUrl = this._testnet
             ? "https://api.hyperliquid-testnet.xyz"
             : "https://api.hyperliquid.xyz";
@@ -1206,14 +2342,8 @@ export class HyperliquidAdapter {
      * Action type: approveBuilderFee
      */
     async approveBuilderFee(builder, maxFeeRate) {
-        const action = {
-            type: "approveBuilderFee",
-            hyperliquidChain: this._testnet ? "Testnet" : "Mainnet",
-            signatureChainId: this._testnet ? "0x66eee" : "0xa4b1",
-            maxFeeRate,
-            builder,
-        };
-        return this._sendExchangeAction(action);
+        // USER-signed (HyperliquidSignTransaction EIP-712), master only — never the L1 scheme.
+        return this._signAndSendUserAction("approveBuilderFee", { maxFeeRate, builder: builder.toLowerCase() });
     }
     /**
      * Vault deposit/withdraw.
@@ -1231,15 +2361,12 @@ export class HyperliquidAdapter {
      * Delegate/undelegate tokens for staking.
      */
     async tokenDelegate(validator, wei, isUndelegate = false) {
-        const action = {
-            type: "tokenDelegate",
-            hyperliquidChain: this._testnet ? "Testnet" : "Mainnet",
-            signatureChainId: this._testnet ? "0x66eee" : "0xa4b1",
-            validator,
-            isUndelegate,
-            wei,
-        };
-        return this._sendExchangeAction(action);
+        // USER-signed staking action (master only). `wei` is a uint64 sent as a JSON number,
+        // so it must be an exact safe integer.
+        if (!/^\d+$/.test(wei) || !Number.isSafeInteger(Number(wei)) || Number(wei) === 0) {
+            throw new PerpError("INVALID_PARAMS", `Hyperliquid tokenDelegate wei must be a positive integer ≤ ${Number.MAX_SAFE_INTEGER} (got ${wei})`, { exchange: "hyperliquid" });
+        }
+        return this._signAndSendUserAction("tokenDelegate", { validator: validator.toLowerCase(), wei: Number(wei), isUndelegate });
     }
     /**
      * Claim staking rewards.
@@ -1326,7 +2453,7 @@ export class HyperliquidAdapter {
         return this._infoPost({ type: "delegations", user: this._address });
     }
     /**
-     * POST to /info endpoint.
+     * POST to /info endpoint (all reads — no SDK). A non-2xx response throws.
      */
     async _infoPost(body) {
         const baseUrl = this._testnet
@@ -1337,6 +2464,14 @@ export class HyperliquidAdapter {
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify(body),
         });
+        if (!res.ok) {
+            const text = await res.text();
+            // HTTP 429 = the IP weight budget is spent (docs "Rate limits and user limits": "REST requests
+            // share an aggregated weight limit of 1200 per minute") → typed RATE_LIMITED.
+            if (res.status === 429)
+                throw rateLimitedError("hyperliquid", res.headers.get("retry-after"), `info ${String(body.type)}: ${text}`);
+            throw new PerpError("EXCHANGE_ERROR", `Hyperliquid info ${String(body.type)} failed (${res.status}): ${text.slice(0, 200)}`, { exchange: "hyperliquid" });
+        }
         return res.json();
     }
     /**
@@ -1346,17 +2481,8 @@ export class HyperliquidAdapter {
     async exchangeAction(action) {
         return this._signAndSendAction(action);
     }
-    /**
-     * Send a raw exchange action through the SDK.
-     * Used for methods not directly exposed by the SDK.
-     */
+    /** Sign (L1 scheme, active signer tier) and send an exchange action. */
     async _sendExchangeAction(action) {
-        const exchange = this.sdk.exchange;
-        // Try using the SDK's internal postAction if available
-        if (typeof exchange.postAction === "function") {
-            return exchange.postAction(action);
-        }
-        // Fallback: sign and send directly (bypasses SDK)
         return this._signAndSendAction(action);
     }
 }