perp-cli 0.14.3 → 0.16.0

package/dist/exchanges/hyperliquid.d.ts

@@ -1,20 +1,21 @@
-import type { ExchangeAdapter, ExchangeMarketInfo, ExchangePosition, ExchangeOrder, ExchangeBalance, ExchangeTrade, ExchangeFundingPayment, ExchangeKline } from "./interface.js";
+import type { ExchangeAdapter, ExchangeMarketInfo, ExchangePosition, ExchangeOrder, ExchangeBalance, ExchangeTrade, ExchangePublicTrade, ExchangeFundingPayment, ExchangeKline, FundingHistoryRow } from "./interface.js";
 import type { ResolvedSlippage } from "./slippage.js";
 import type { EvmSigner } from "../signer/index.js";
 import type { AgentMeta } from "../settings.js";
+import { PerpError } from "../errors.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
+ * Map a TIF input to HL's native value. 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.
+ * HL (no FOK emulation) → 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).
+ * Slippage-bounded IOC protection price.
  *
  * `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
@@ -29,8 +30,8 @@ export declare function hlProtectionPrice(reference: number, side: "buy" | "sell
     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).
+ * A USER-SUPPLIED limit / trigger / modify price checked against HL's price grid:
+ * 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."
@@ -59,7 +60,7 @@ export declare function hlAlignPriceToGrid(price: string, szDecimals: number, ma
 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]`:
+ * perp-order lane). 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;
@@ -127,6 +128,18 @@ export declare const HL_MARKET_META_TTL_MS: number;
 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;
+/**
+ * Margin tiers of a universe entry. Docs "Margin tiers": "For IDs less than 50, there is a single
+ * tier with max leverage equal to the ID" — those tables are not in `marginTables`, so the
+ * implicit tier is emitted instead of null. Unknown ids ≥ 50 → null.
+ */
+export declare function hlMarginTiersOf(marginTableId: unknown, tierMap: ReadonlyMap<number, Array<{
+    lowerBound: number;
+    maxLeverage: number;
+}>>): Array<{
+    lowerBound: number;
+    maxLeverage: number;
+}> | null;
 /** Venue margin restriction of a universe entry: strictIsolated (no margin removal) / noCross; null = unrestricted. */
 export declare function hlMarginModeOf(asset: {
     marginMode?: string;
@@ -165,6 +178,101 @@ export declare function hlUserActionRejection(type: string, e: unknown): unknown
  * parse failures (no envelope) are returned unchanged.
  */
 export declare function hlL1ActionRejection(type: string, e: unknown): unknown;
+/**
+ * candleSnapshot intervals (docs "Candle snapshot": "Supported intervals") with their nominal
+ * length. Anything else is answered 422 "Failed to deserialize" (live 2026-10-19, "7m"), so it is
+ * refused as INVALID_PARAMS before sending. "1M" buckets are 30 days, not calendar months
+ * (live: consecutive 1M opens 30 d apart); "1w" buckets open on Thursday 00:00 UTC.
+ */
+export declare const HL_CANDLE_INTERVAL_MS: Readonly<Record<string, number>>;
+/** Docs "Candle snapshot": "Only the most recent 5000 candles are available". */
+export declare const HL_CANDLE_CAP = 5000;
+/** Earliest candleSnapshot start (unix ms) for `interval` at `now`: now − 5000 × interval. Unknown interval → NaN. */
+export declare function hlEarliestCandleStart(interval: string, now?: number): number;
+/** recentTrades returns the last 10 trades, with no count parameter (live 2026-10-19). */
+export declare const HL_RECENT_TRADES_CAP = 10;
+/** l2Book returns at most 20 levels per side (docs l2Book; live 2026-10-19). */
+export declare const HL_BOOK_LEVELS_CAP = 20;
+/** Largest `market funding --limit` (hourly rows ≈ 208 days) and the page guard of one read. */
+export declare const HL_FUNDING_HISTORY_MAX_LIMIT = 5000;
+/**
+ * Open positions of one clearinghouseState (info `clearinghouseState` {user[, dex]}): rows with
+ * szi 0 dropped. The ONE mapper of the keyed `getPositions` and the public-address read
+ * (`account positions --address`); `symbolOf` names the row (keyed: the adapter's display name,
+ * public: the plain coin — "BTC", HIP-3 "xyz:GOLD").
+ */
+export declare function hlPositionRows(state: Record<string, unknown>, symbolOf: (coin: string) => string): ExchangePosition[];
+/** The user's account abstraction mode (info `userAbstraction`, see HyperliquidAdapter._getAbstractionMode). */
+export type HlAbstractionMode = "unified" | "standard" | "portfolio" | "default" | "dexAbstraction";
+/**
+ * info `userAbstraction` answer → mode. Per SSOT Rule #2: an unrecognized venue response throws —
+ * no silent default.
+ */
+export declare function hlAbstractionModeOf(raw: unknown): HlAbstractionMode;
+/** Reads hlBalanceOf() makes only when the mode needs them (the keyed adapter: cached; the public path: raw). */
+export interface HlBalanceReads {
+    /** Spot balance row of the dex's collateral token (matched by token index); row null = none held. */
+    spotCollateralRow(): Promise<{
+        row: Record<string, unknown> | null;
+        balances: Record<string, unknown>[];
+        token: number;
+        portfolioMarginRatio?: unknown;
+    }>;
+    /** Collateral token index of the dex (info `meta{dex}.collateralToken`). */
+    collateralToken(): Promise<number>;
+    /** USDC price per spot token index (hlSpotUsdPricesOf over info `spotMetaAndAssetCtxs`); portfolio mode only. */
+    spotUsdPrices(): Promise<Map<number, number>>;
+}
+/**
+ * Portfolio-margin collateral rows: the venue returns an `ltv` on exactly the eligible collateral
+ * tokens (live 2026-10-26: USDC, HYPE, USDT0 carry it, memecoins do not; unified-mode rows never
+ * do), plus the dex's collateral token itself.
+ */
+export declare function hlIsPortfolioCollateral(row: Record<string, unknown>, collateralToken: number): boolean;
+/**
+ * USDC price of each spot token (index → price) from info `spotMetaAndAssetCtxs`: the mark of its
+ * USDC-quoted pair (quote token 0); several pairs for one token → the one with the larger 24h
+ * notional. USDC itself is 1. Malformed payload → EXCHANGE_ERROR (never a guessed price).
+ */
+export declare function hlSpotUsdPricesOf(raw: unknown): Map<number, number>;
+/**
+ * Balance of one perp dex ("" = native) from its clearinghouseState and the user's abstraction
+ * mode — the one implementation behind HyperliquidAdapter.getBalance() and the keyless
+ * `account balance --address`. `notes` are the human warnings getBalance() writes to stderr.
+ *
+ * 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: one portfolio of every eligible collateral token (HYPE, BTC, USDC,
+ * USDT — the rows the venue marks with `ltv`). The collateral token's `total` already moves with
+ * perp PnL (it can be negative = borrowed), so equity = Σ eligible `total` × spot USDC price —
+ * live 2026-10-26 this equals the venue's own `portfolio` account value minus vault equity.
+ * `available` stays the collateral token's total − hold. The balance carries `collateral` (the
+ * priced rows) and `portfolioMarginRatio` (liquidatable above 0.95, docs trading/portfolio-margin).
+ */
+/** One priced portfolio-margin collateral row (HlPortfolioBalance.collateral). */
+export interface HlPortfolioCollateral {
+    token: string;
+    total: string;
+    priceUsd: string;
+    valueUsd: string;
+    ltv: string | null;
+    borrowed: string | null;
+    supplied: string | null;
+}
+/** Portfolio-margin balance: the ExchangeBalance plus its priced collateral and margin ratio. */
+export type HlPortfolioBalance = ExchangeBalance & {
+    collateral: HlPortfolioCollateral[];
+    portfolioMarginRatio: string | null;
+};
+export declare function hlBalanceOf(state: Record<string, unknown>, mode: HlAbstractionMode, dex: string, reads: HlBalanceReads): Promise<{
+    balance: ExchangeBalance | HlPortfolioBalance;
+    notes: string[];
+}>;
 export declare class HyperliquidAdapter implements ExchangeAdapter {
     readonly name = "hyperliquid";
     readonly chain = "evm";
@@ -178,6 +286,8 @@ export declare class HyperliquidAdapter implements ExchangeAdapter {
      * semantics for accounts that have never opted in. Codex v0.12.12 final QA #1.
      */
     isUnifiedAccount: boolean;
+    /** The account abstraction mode resolved in init() (null until then / without an address). */
+    accountMode: HlAbstractionMode | null;
     private _address;
     private _privateKey;
     private _testnet;
@@ -203,9 +313,19 @@ export declare class HyperliquidAdapter implements ExchangeAdapter {
      * configured. Set by createHyperliquid — the adapter never reads settings.
      */
     builderFee: BuilderFeeGate | null;
+    /** recentTrades' fixed tape size (no paging): `market trades` defaults to min(20, this). */
+    readonly recentTradesCap = 10;
     constructor(privateKey?: string, testnet?: boolean);
     /** Set the HIP-3 deployed perp dex to query/trade on. */
     setDex(dex: string): void;
+    /**
+     * An independent adapter for HIP-3 dex `dex` ("" = native perps) with this adapter's account
+     * configuration (key / signers / address / network / builder gate) and its OWN market state
+     * (asset maps, markets cache, delisted sets, in-flight reads). Fan-outs over dexes use this:
+     * Object.create(adapter) + setDex() shared the prototype's maps, so setDex cleared the native
+     * adapter's asset map and the dex copies served the native markets cache.
+     */
+    forDex(dex: string): HyperliquidAdapter;
     get dex(): string;
     get address(): string;
     /**
@@ -269,11 +389,41 @@ export declare class HyperliquidAdapter implements ExchangeAdapter {
     /** 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>;
+    /** SYMBOL_NOT_FOUND for a coin the venue does not list (on this adapter's dex), with the listing command. */
+    private _unknownSymbol;
     getMarkets(): Promise<ExchangeMarketInfo[]>;
-    getOrderbook(symbol: string): Promise<{
+    /** Display names of the delisted assets seen by the last getMarkets() (meta isDelisted). */
+    private _delisted;
+    /** Asset-map keys of the delisted assets in `meta` (_loadAssetMap): "MATIC-PERP"; HIP-3 "km:US500" and "US500". */
+    private _delistedAssets;
+    /**
+     * Why `symbol` is not in getMarkets(): it is delisted (message), or null when it is not a
+     * delisted asset. Read after getMarkets() (or once the asset map is loaded). `market info` uses
+     * it to say "delisted" rather than "not found" — the asset map still resolves it for orders /
+     * positions / history. A HIP-3 bare name ("US500" on --dex km) is matched by its venue coin.
+     */
+    delistedMessage(symbol: string): string | null;
+    /** SYMBOL_NOT_FOUND (details.reason "delisted") for a delisted `symbol`, with a dex-aware remediation; null when listed. */
+    delistedError(symbol: string): PerpError | null;
+    /**
+     * Per-symbol MARKET-DATA reads (trades, funding, book, klines): the symbol must resolve
+     * (SYMBOL_NOT_FOUND) and must not be delisted — HL keeps serving a delisted coin's last tape
+     * (MATIC: trades from 2024-09-09) and zero-rate funding rows stamped every hour (live
+     * 2026-10-19), which read as a live market. Orders / positions / history do not call this.
+     */
+    private _listedMarket;
+    /**
+     * Public order-book read (`market book`, bots, MCP): l2Book serves at most HL_BOOK_LEVELS_CAP
+     * (20) levels per side and cannot be paged, so a `depth` above it is INVALID_PARAMS naming the
+     * cap. Refuses delisted markets (_listedMarket). Order paths use _l2Book (no delisted gate):
+     * a reduce-only close of a delisted asset must still get its reference price.
+     */
+    getOrderbook(symbol: string, depth?: number): Promise<{
         bids: [string, string][];
         asks: [string, string][];
     }>;
+    /** l2Book of `symbol` (native or this adapter's dex), no listing gate. Unlisted coin → SYMBOL_NOT_FOUND. */
+    private _l2Book;
     /**
      * 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").
@@ -305,7 +455,7 @@ export declare class HyperliquidAdapter implements ExchangeAdapter {
      */
     _getAbstractionMode(opts?: {
         fresh?: boolean;
-    }): Promise<"unified" | "standard" | "portfolio" | "default" | "dexAbstraction">;
+    }): Promise<HlAbstractionMode>;
     /** Collateral token index of this adapter's perp dex (info `meta{dex}.collateralToken`; 0 = USDC on native perps). */
     private _collateralTokenIdx;
     _getCollateralToken(): Promise<number>;
@@ -367,11 +517,11 @@ export declare class HyperliquidAdapter implements ExchangeAdapter {
      */
     private _validateOrderFill;
     /**
-     * Market order = slippage-bounded IOC limit (design §13.2, §13.10 #1/#5) for
+     * Market order = slippage-bounded IOC limit 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
+     * Reference price (the single declared source): 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
@@ -396,7 +546,8 @@ export declare class HyperliquidAdapter implements ExchangeAdapter {
     /**
      * 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.
+     * (_l2Book passes the dex). Either side missing / non-positive → PRICE_STALE. Not gated on
+     * delisting: a reduce-only market close of a delisted asset is sent (the venue decides).
      */
     referencePrice(symbol: string): Promise<number>;
     /**
@@ -483,7 +634,7 @@ export declare class HyperliquidAdapter implements ExchangeAdapter {
     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
+     * Amend 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.
@@ -494,8 +645,24 @@ export declare class HyperliquidAdapter implements ExchangeAdapter {
         limitPrice?: string;
         reduceOnly?: boolean;
     }): Promise<unknown>;
-    getRecentTrades(symbol: string, limit?: number): Promise<ExchangeTrade[]>;
-    getKlines(symbol: string, interval: string, startTime: number, endTime: number): Promise<ExchangeKline[]>;
+    /**
+     * recentTrades: the venue's last HL_RECENT_TRADES_CAP (10) trades — no count parameter, no
+     * paging. `limit` undefined = the venue max (10); an explicit `limit` above 10 is INVALID_PARAMS
+     * naming the cap (never fewer rows than asked, silently). Row `symbol` is the raw venue coin
+     * ("BTC", "km:US500"), as in the WS codec — not the "BTC-PERP" display name of `market list`.
+     */
+    getRecentTrades(symbol: string, limit?: number): Promise<ExchangePublicTrade[]>;
+    /**
+     * candleSnapshot. Only the most recent HL_CANDLE_CAP (5000) candles of an interval exist (docs)
+     * and older ones cannot be paged to: a `startTime` before hlEarliestCandleStart() is refused
+     * up front (INVALID_PARAMS naming the earliest allowed start) — never a silently shortened
+     * range. `closed` (additive) is false on the in-progress candle (close time `T`, or open +
+     * interval when `T` is absent, still in the future). "1M" = 30-day buckets; "1w" opens
+     * Thursday 00:00 UTC.
+     */
+    getKlines(symbol: string, interval: string, startTime: number, endTime: number): Promise<Array<ExchangeKline & {
+        closed: boolean;
+    }>>;
     /**
      * Order history: POST /info {type:"historicalOrders"} ("Retrieve a user's historical orders",
      * at most 2000 most recent; live 2026-10-13: newest first, each order listed once per status —
@@ -529,16 +696,20 @@ export declare class HyperliquidAdapter implements ExchangeAdapter {
      * adapter keeps "<dex>:…" coins, the native adapter keeps native perp coins only.
      */
     private _inHistoryScope;
-    getFundingHistory(symbol: string, limit?: number): Promise<{
-        time: number;
-        rate: string;
-        price: string | null;
-    }[]>;
+    /**
+     * The last `limit` hourly funding settlements. HL funding is hourly, so the window starts
+     * `limit + 1` hours back (one spare hour for a settlement not yet published), and fundingHistory
+     * pages are read forward from the last row's time (docs: at most 500 elements per response;
+     * "use the last returned timestamp as the next startTime") — deduped by time, oldest first.
+     */
+    getFundingHistory(symbol: string, limit?: number): Promise<FundingHistoryRow[]>;
+    /** Every fundingHistory row of `coin` since `startTime`, paged forward (500 per response), deduped by time, oldest first. */
+    private _fundingHistorySince;
     /**
      * 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):
+     * Pricing:
      * - 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.
@@ -696,12 +867,18 @@ export declare class HyperliquidAdapter implements ExchangeAdapter {
      */
     claimRewards(): Promise<unknown>;
     /**
-     * List all available HIP-3 deployed perp dexes.
+     * List the HIP-3 deployed perp dexes: allPerpMetas (universe per dex; index 0 = native perps)
+     * joined by index with perpDexs (name, deployer — live 2026-10-19 both list the dexes in the
+     * same order). `assets` holds the LIVE (non-delisted) assets only; `delistedAssets` the rest and
+     * `delisted` is true when every asset of the dex is delisted (km, flx, hyna, cash, vntl, abcd on
+     * 2026-10-19). Delisted dexes stay listed: accounts may still hold positions there.
      */
     listDeployedDexes(): Promise<{
         name: string;
         deployer: string;
         assets: string[];
+        delistedAssets: string[];
+        delisted: boolean;
     }[]>;
     /**
      * Get referral info.