perp-cli 0.12.17 → 0.14.0

package/dist/exchanges/hyperliquid.d.ts

@@ -1,20 +1,183 @@
-import { Hyperliquid } from "hyperliquid";
 import type { ExchangeAdapter, ExchangeMarketInfo, ExchangePosition, ExchangeOrder, ExchangeBalance, ExchangeTrade, ExchangeFundingPayment, ExchangeKline } from "./interface.js";
+import type { ResolvedSlippage } from "./slippage.js";
 import type { EvmSigner } from "../signer/index.js";
 import type { AgentMeta } from "../settings.js";
+import { type BuilderApproval, type BuilderDecision, type BuilderFeeGate, type BuilderTarget } from "./builder-fee.js";
+/** HL native time-in-force values. */
+export type HlTif = "Gtc" | "Ioc" | "Alo";
+/**
+ * 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 declare function hlTif(raw: string): HlTif;
+/** HL lot step implied by szDecimals ("1" for 0, "0.001" for 3) — sizes are floored to it (floorSize). */
+export declare function hlSizeStep(szDecimals: number): string;
+/**
+ * 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 declare function hlProtectionPrice(reference: number, side: "buy" | "sell", bps: number, szDecimals: number, maxDecimals: 6 | 8): {
+    protectionPrice: string;
+    appliedBps: number;
+};
+/**
+ * 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 declare function hlRequirePriceOnGrid(price: string, szDecimals: number, maxDecimals: 6 | 8, what: string): string;
+/** CCTP destinations for Hyperliquid withdrawals (Circle CCTP domain ids: Ethereum 0, Arbitrum 3, Base 6). */
+export type HlCctpChain = "arbitrum" | "ethereum" | "base";
+export declare const HL_CCTP_ROUTES: Record<HlCctpChain, {
+    cctpDomain: number;
+    forwardingFeeUsdc: string | 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 declare function hlAlignPriceToGrid(price: string, szDecimals: number, maxDecimals: 6 | 8, direction: "down" | "up"): string;
+/**
+ * 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 declare function assertHlAppliedBps(appliedBps: number, what: string): Promise<void>;
+/**
+ * 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 declare function hlIocOutcome(raw: unknown): {
+    filledSize: string;
+    final: true;
+} | null;
+/**
+ * Decimal amount string for HL actions ("12.50" → "12.5"). Non-positive / non-numeric → INVALID_PARAMS
+ * (nothing is rounded or substituted).
+ */
+export declare function hlAmountString(amount: string): string;
+/**
+ * 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 declare function hlValidateTwapResult(result: unknown, what: string): void;
+/** HL TWAP running time bounds in minutes: "from 5 minutes to 7 days" (docs trading/order-types, TWAP details). */
+export declare const HL_TWAP_MIN_MINUTES = 5;
+export declare const HL_TWAP_MAX_MINUTES: number;
+/** HL TWAP "$100 minimum total order size" (same page). */
+export declare 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 declare function hlAssertTwapBounds(symbol: string, size: string, durationMinutes: number, markPrice: number): void;
+/**
+ * "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 declare function hlTriggerKind(side: "buy" | "sell", trigger: number, reference: number): "tp" | "sl";
+/** 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 declare const HL_SETTINGS_FILL_MARKETS = 5;
+export declare function hlIsSpotCoin(coin: string): boolean;
+/**
+ * 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 declare function hlDestination(destination: string): string;
+/**
+ * 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 declare const HL_MARKET_META_TTL_MS: number;
+/**
+ * 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 declare const HL_ABSTRACTION_TTL_MS = 60000;
+/** Cache-key prefix of the abstraction mode for a network (invalidateCache prefix: every address). */
+export declare function hlAbstractionCachePrefix(network: string): string;
+/** Venue margin restriction of a universe entry: strictIsolated (no margin removal) / noCross; null = unrestricted. */
+export declare function hlMarginModeOf(asset: {
+    marginMode?: string;
+    onlyIsolated?: boolean;
+}): "strictIsolated" | "noCross" | null;
+/** HIP-3 (builder-deployed) asset ids start at 110000 (110000 + dexIndex × 10000 + universe index). */
+export declare const HIP3_MIN_ASSET_ID = 110000;
+/**
+ * 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 declare const HL_MARKET_TPSL_SLIPPAGE_BPS = 1000;
+/** A `{"status":"err","response":…}` envelope from POST /exchange: the venue processed the request and refused it. */
+export declare class HlErrResponse extends Error {
+    constructor(message: string);
+}
+/**
+ * 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 declare function hlUserActionRejection(type: string, e: unknown): unknown;
+/**
+ * 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 declare function hlL1ActionRejection(type: string, e: unknown): unknown;
 export declare class HyperliquidAdapter implements ExchangeAdapter {
     readonly name = "hyperliquid";
     readonly chain = "evm";
     readonly aliases: readonly ["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: boolean;
-    private sdk;
     private _address;
     private _privateKey;
     private _testnet;
@@ -25,18 +188,41 @@ export declare class HyperliquidAdapter implements ExchangeAdapter {
     private _assetMap;
     private _assetMapReverse;
     private _szDecimalsMap;
+    /** symbol → venue marginMode restriction (meta universe `marginMode` / `onlyIsolated`); absent = none. */
+    private _marginModeMap;
     /** HIP-3 deployed perp dex name. Empty string = native (validator) perps. */
     private _dex;
+    /** Why the last asset-map load refused to map the dex (unknown dex / asset id below the HIP-3 range). */
+    private _assetMapError;
     private static _lastNonce;
     private _marketsCache;
     private _marketsCacheTime;
     private static readonly CACHE_TTL;
+    /**
+     * Builder-fee gate (settings builder.hyperliquid + confirmed master approval); null = not
+     * configured. Set by createHyperliquid — the adapter never reads settings.
+     */
+    builderFee: BuilderFeeGate | null;
     constructor(privateKey?: string, testnet?: boolean);
     /** Set the HIP-3 deployed perp dex to query/trade on. */
     setDex(dex: string): void;
     get dex(): string;
-    get client(): Hyperliquid;
     get address(): string;
+    /**
+     * 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.
+     */
+    builderDecision(assetIndex: number | null): Promise<BuilderDecision>;
+    /**
+     * 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).
+     */
+    private _orderAction;
+    /**
+     * 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).
+     */
+    builderApprovalOf(target: BuilderTarget): Promise<BuilderApproval>;
     get isTestnet(): boolean;
     /** Inject an external EVM signer. Call before init() to skip LocalEvmSigner creation. */
     setSigner(signer: EvmSigner): void;
@@ -57,6 +243,15 @@ export declare class HyperliquidAdapter implements ExchangeAdapter {
     /** Resolve the active signer across three tiers. */
     private _resolveSigner;
     init(): Promise<void>;
+    /**
+     * 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.
+     */
+    private _metaCached;
     /** Load asset index map — supports native and HIP-3 dex. */
     private _loadAssetMap;
     /**
@@ -64,43 +259,105 @@ export declare class HyperliquidAdapter implements ExchangeAdapter {
      * Handles: "ICP" → "ICP-PERP", "BTC-PERP" → "BTC-PERP", "km:GOOGL" → "km:GOOGL"
      */
     resolveSymbol(symbol: string): string;
-    /** Get szDecimals for a symbol (cached from init/getMeta) */
+    /** The asset-map key equal to `upper` ignoring case, when exactly one exists (kPEPE-PERP for KPEPE-PERP). */
+    private _caseInsensitive;
+    /**
+     * 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: string): number;
-    /** HL official price rounding: 5 significant figures */
-    private _hlRoundPrice;
+    /** Lot step of a market from the loaded `meta` szDecimals (precision.lotStepOf) — no metaAndAssetCtxs / allMids read per order. */
+    lotStepOf(symbol: string): string;
     getAssetIndex(symbol: string): Promise<number>;
     getMarkets(): Promise<ExchangeMarketInfo[]>;
     getOrderbook(symbol: string): Promise<{
         bids: [string, string][];
         asks: [string, string][];
     }>;
+    /**
+     * 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").
+     */
+    private _venueCoin;
+    /** Display symbol for a venue coin: a native perp coin "BTC" → "BTC-PERP"; anything else unchanged. */
+    private _displaySymbol;
     private ensureAddress;
+    /** The in-flight clearinghouseState read: parallel callers (getBalance + getPositions) share one request. */
+    private _chsInFlight;
     /** Read-through cached clearinghouseState — returns cached data if fresh */
     private _getClearinghouseState;
     /**
      * 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"`.
-     */
-    _getAbstractionMode(): Promise<"unified" | "standard" | "portfolio">;
-    /** Cached spot clearinghouse state — shared between getBalance() and HyperliquidSpotAdapter */
-    _getSpotClearinghouseState(): Promise<Record<string, unknown>>;
+     * Endpoint: `POST /info {"type":"userAbstraction","user":"0x..."}`.
+     */
+    _getAbstractionMode(opts?: {
+        fresh?: boolean;
+    }): Promise<"unified" | "standard" | "portfolio" | "default" | "dexAbstraction">;
+    /** Collateral token index of this adapter's perp dex (info `meta{dex}.collateralToken`; 0 = USDC on native perps). */
+    private _collateralTokenIdx;
+    _getCollateralToken(): Promise<number>;
+    /** Cached spot clearinghouse state (raw venue shape) — shared between getBalance() and HyperliquidSpotAdapter */
+    _getSpotClearinghouseState(opts?: {
+        fresh?: boolean;
+    }): Promise<Record<string, unknown>>;
+    /** Spot balance row of this dex's collateral token (matched by token index, not by coin name); null = none held. */
+    private _spotCollateralRow;
     getBalance(): Promise<ExchangeBalance>;
     getPositions(): Promise<ExchangePosition[]>;
+    /**
+     * 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.
+     */
+    marketLeverage(symbol: string): Promise<number>;
+    /**
+     * 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.
+     */
+    getMarketSettings(): Promise<Array<{
+        symbol: string;
+        leverage: number;
+        marginMode: "cross" | "isolated";
+    }>>;
+    /**
+     * 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".
+     */
     getOpenOrders(): Promise<ExchangeOrder[]>;
+    /** 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: string): string;
+    private _oidOf;
     private _invalidateAccountCache;
     /**
      * Validate that an HL order actually filled.
@@ -109,15 +366,60 @@ export declare class HyperliquidAdapter implements ExchangeAdapter {
      * Each status is one of: { filled: { totalSz, avgPx, oid } }, { resting: { oid } }, { error: "msg" }
      */
     private _validateOrderFill;
-    marketOrder(symbol: string, side: "buy" | "sell", size: string, opts?: {
-        reduceOnly?: boolean;
-    }): Promise<unknown>;
     /**
-     * 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.
+     * 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.
+     */
+    marketOrder(symbol: string, side: "buy" | "sell", size: string, opts: {
+        reduceOnly: boolean;
+        slippage: ResolvedSlippage;
+        clientOrderId?: string;
+    }): Promise<{
+        clientOrderId?: string | undefined;
+        protection: {
+            referencePrice: string;
+            protectionPrice: string;
+            appliedBps: number;
+        };
+        sentSize: string;
+    }>;
+    /**
+     * 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.
      */
-    private _dexMarketOrder;
+    referencePrice(symbol: string): Promise<number>;
+    /**
+     * 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.
+     */
+    markPrice(symbol: string): Promise<number>;
+    /**
+     * 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).
+     */
+    computeProtectionPrice(symbol: string, side: "buy" | "sell", slippage: ResolvedSlippage): Promise<{
+        referencePrice: string;
+        protectionPrice: string;
+        appliedBps: number;
+    }>;
+    /** Definite IOC outcome of a raw order response (see hlIocOutcome). */
+    iocOutcomeOf(raw: unknown): {
+        filledSize: string;
+        final: true;
+    } | null;
     /**
      * Sign and send any exchange action via raw EIP-712 signing.
      * Bypasses the SDK entirely — works for order, batchModify, twapOrder, etc.
@@ -132,20 +434,62 @@ export declare class HyperliquidAdapter implements ExchangeAdapter {
      * does not exist" error.
      */
     private static _normalizeAction;
+    /** Monotonic ms nonce: unique even for rapid-fire requests in the same millisecond. */
+    private static _nextNonce;
+    private get _network();
+    /**
+     * 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).
+     */
     private _signAndSendAction;
+    /**
+     * 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.
+     */
+    private _signAndSendUserAction;
+    /** POST /exchange request timeout: a request the venue never answers must not hang the CLI. */
+    static readonly EXCHANGE_TIMEOUT_MS = 30000;
+    /**
+     * 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.
+     */
+    private _postExchange;
+    /** One order wire (HL `order` action entry); p/s trailing zeros removed (HL API requirement). */
+    private _orderWire;
     /**
      * Place an order via raw exchange API with EIP-712 signing.
      * This bypasses the SDK's symbolConversion and supports dex-specific orders.
      */
     private _rawPlaceOrder;
+    /**
+     * 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.
+     */
+    alignComputedPrice(symbol: string, side: "buy" | "sell", price: string): Promise<string>;
     limitOrder(symbol: string, side: "buy" | "sell", price: string, size: string, opts?: {
         reduceOnly?: boolean;
         tif?: string;
+        clientOrderId?: string;
     }): Promise<unknown>;
+    /**
+     * 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.
+     */
+    cancelByCloid(symbol: string, cloid: string): Promise<unknown>;
     cancelOrder(symbol: string, orderId: string): Promise<unknown>;
     cancelAllOrders(symbol?: string): Promise<unknown[]>;
+    /**
+     * 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.
+     */
     editOrder(symbol: string, orderId: string, price: string, size: string): Promise<unknown>;
-    setLeverage(symbol: string, leverage: number, marginMode?: "cross" | "isolated"): Promise<any>;
+    setLeverage(symbol: string, leverage: number, marginMode?: "cross" | "isolated"): Promise<unknown>;
     stopOrder(symbol: string, side: "buy" | "sell", size: string, triggerPrice: string, opts?: {
         limitPrice?: string;
         reduceOnly?: boolean;
@@ -163,12 +507,30 @@ export declare class HyperliquidAdapter implements ExchangeAdapter {
     /**
      * 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).
      */
     triggerOrder(symbol: string, side: "buy" | "sell", size: string, triggerPrice: string, tpsl: "tp" | "sl", opts?: {
         isMarket?: boolean;
+        limitPrice?: string;
         reduceOnly?: boolean;
         grouping?: string;
+        slippage?: ResolvedSlippage;
     }): Promise<unknown>;
+    /** Open trigger orders of `coin` (frontendOpenOrders rows with isTrigger), by oid. */
+    private _triggerOids;
+    /**
+     * 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).
+     */
+    private _newTriggerOid;
     /**
      * Place a TWAP order.
      * Python SDK: not available in old SDK, available via raw exchange action.
@@ -182,29 +544,52 @@ export declare class HyperliquidAdapter implements ExchangeAdapter {
      * Cancel a TWAP order.
      */
     twapCancel(symbol: string, twapId: number): Promise<unknown>;
+    /** Venue margin restriction of `symbol` (meta marginMode / onlyIsolated); null = unrestricted. */
+    marginModeOf(symbol: string): "strictIsolated" | "noCross" | 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.
      */
-    updateLeverage(symbol: string, leverage: number, isCross?: boolean): Promise<any>;
+    updateLeverage(symbol: string, leverage: number, isCross?: boolean): Promise<unknown>;
     /**
-     * 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.
      */
-    updateIsolatedMargin(symbol: string, amount: number): Promise<any>;
+    updateIsolatedMargin(symbol: string, amount: number): Promise<unknown>;
     /**
-     * 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).
      */
-    withdraw(amount: string, destination: string, _opts?: {
+    withdraw(amount: string, destination: string, opts?: {
         assetId?: number;
         routeType?: number;
-    }): Promise<any>;
+        chain?: HlCctpChain;
+    }): Promise<unknown>;
+    /**
+     * Send USDC to another Hyperliquid account — user-signed `usdSend` (master only),
+     * python SDK usd_transfer.
+     */
+    usdTransfer(amount: number, destination: string): Promise<unknown>;
     /**
-     * Transfer USD between accounts on Hyperliquid L1.
-     * Python SDK: usd_transfer(amount, destination)
+     * Move USDC between this account's spot and perp balances — user-signed
+     * `usdClassTransfer` (master only), python SDK usd_class_transfer.
      */
-    usdTransfer(amount: number, destination: string): Promise<any>;
+    usdClassTransfer(amount: string, toPerp: boolean): Promise<unknown>;
+    /**
+     * 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).
+     */
+    agentSendAsset(amount: string, toPerp: boolean): Promise<unknown>;
+    /** "<name>:<tokenId>" of this dex's collateral token (meta{dex}.collateralToken → spotMeta tokens). */
+    private _collateralTokenWire;
     /**
      * Create a sub-account.
      */
@@ -214,20 +599,42 @@ export declare class HyperliquidAdapter implements ExchangeAdapter {
      */
     subAccountTransfer(subAccountUser: string, isDeposit: boolean, amount: number): Promise<unknown>;
     /**
-     * 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.
      */
-    modifyOrder(symbol: string, orderId: number, newSide: "buy" | "sell", newPrice: string, newSize: string, opts?: {
-        reduceOnly?: boolean;
+    modifyOrder(symbol: string, orderId: number, newSide: "buy" | "sell", newPrice: string, newSize: string, opts: {
+        reduceOnly: boolean;
+        tif: HlTif;
+        cloid?: string | null;
     }): Promise<unknown>;
+    /**
+     * 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: unknown, what: string): void;
+    private _validateModifyResult;
     /**
      * Schedule cancel: cancel all orders at a future time.
      * Max 10 triggers per day.
      */
     scheduleCancel(timeMs?: number): Promise<unknown>;
     /**
-     * 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).
      */
-    autoSetReferrer(code?: string): Promise<void>;
+    setReferrer(code: string): Promise<unknown>;
     /**
      * Get funding history for a symbol.
      */
@@ -243,7 +650,8 @@ export declare class HyperliquidAdapter implements ExchangeAdapter {
     /**
      * Query a specific order by OID.
      */
-    queryOrder(orderId: number): Promise<any>;
+    /** info `orderStatus`: `oid` "Either u64 representing the order id or 16-byte hex string representing the client order id". */
+    queryOrder(orderId: number | string): Promise<any>;
     /**
      * Approve a builder fee.
      * Action type: approveBuilderFee
@@ -298,7 +706,7 @@ export declare class HyperliquidAdapter implements ExchangeAdapter {
      */
     getDelegations(): Promise<unknown>;
     /**
-     * POST to /info endpoint.
+     * POST to /info endpoint (all reads — no SDK). A non-2xx response throws.
      */
     private _infoPost;
     /**
@@ -306,9 +714,6 @@ export declare class HyperliquidAdapter implements ExchangeAdapter {
      * Used by HyperliquidSpotAdapter to delegate signing.
      */
     exchangeAction(action: Record<string, unknown>): Promise<unknown>;
-    /**
-     * 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. */
     private _sendExchangeAction;
 }