@lifi/perps-sdk-provider-hyperliquid 26.0.0 → 27.0.1

package/dist/types/utils/liquidation.d.ts

@@ -11,38 +11,39 @@
  * - side = 1 (long) or -1 (short)
  * - margin_available = isolated_margin - maintenance_margin_required
  */
+import { type DecimalString } from '@lifi/perps-types';
 /**
- * Calculate the maintenance margin fraction for a Hyperliquid asset.
- *
- * Maintenance margin is half of the initial margin at max leverage.
+ * Maintenance margin fraction for a Hyperliquid asset: half of the initial
+ * margin at max leverage, `1 / (2 × maxLeverage)`.
  *
  * @param maxLeverage - Maximum leverage for the asset (e.g., 50 for BTC)
- * @returns Maintenance margin fraction (e.g., 0.01 for 50x max leverage),
- *   or undefined if maxLeverage is zero
+ * @returns Maintenance margin fraction (`'0.01'` for 50x max leverage)
+ * @throws {PerpsError} `ValidationError` when `maxLeverage` is not a finite
+ *   number above zero.
  * @public
  */
-export declare function calculateMaintenanceMarginRate(maxLeverage: number): number | undefined;
+export declare function calculateMaintenanceMarginRate(maxLeverage: number): DecimalString;
+/** @public */
+export declare const safeCalculateMaintenanceMarginRate: (maxLeverage: number) => string | undefined;
 /**
- * Calculate liquidation price using the exact Hyperliquid formula.
- *
- * For isolated margin, new position prediction. For existing positions,
- * prefer Position.liquidationPrice from the API.
+ * Liquidation price of a new isolated position with the exact Hyperliquid
+ * formula. For an existing position, prefer `Position.liquidationPrice` from
+ * the API.
  *
  * Formula derivation (isolated margin, single position):
- *   margin_per_unit        = entryPrice / leverage
- *   maintenance_per_unit   = entryPrice * mmr
- *   margin_available       = margin_per_unit - maintenance_per_unit
- *   liq_price              = entryPrice - side * margin_available / (1 - mmr * side)
- *
- * Where mmr = 1 / (2 * maxLeverage).
- *
- * @param entryPrice - Position entry price
- * @param leverage - User-selected leverage (e.g., 10)
- * @param isLong - True if long position, false if short
- * @param maxLeverage - Asset's maximum leverage (e.g., 50 for BTC). Determines
- *   the maintenance margin rate: mmr = 1 / (2 * maxLeverage)
- * @returns Estimated liquidation price, or undefined if inputs are invalid
+ *   margin_available = entryPrice × (1 / leverage - mmr)
+ *   liq_price        = entryPrice - side × margin_available / (1 - mmr × side)
+ *
+ * @param leverage - User-selected leverage (e.g., `'10'`)
+ * @param maxLeverage - Asset's maximum leverage (e.g., 50 for BTC). Sets
+ *   mmr = 1 / (2 × maxLeverage).
+ * @returns The estimate, or `undefined` when `leverage` is at or above
+ *   `2 × maxLeverage`, as {@link estimateLiquidationPrice} documents.
+ * @throws {PerpsError} `ValidationError` when `maxLeverage` is not a finite
+ *   number above zero, or on an input that `estimateLiquidationPrice` rejects.
  * @public
  */
 export declare function calculateLiquidationPrice(entryPrice: string, leverage: string, isLong: boolean, maxLeverage: number): string | undefined;
+/** @public */
+export declare const safeCalculateLiquidationPrice: (entryPrice: string, leverage: string, isLong: boolean, maxLeverage: number) => string | undefined;
 //# sourceMappingURL=liquidation.d.ts.map

package/dist/types/utils/liquidation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"liquidation.d.ts","sourceRoot":"","sources":["../../../src/utils/liquidation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAQH;;;;;;;;;GASG;AACH,wBAAgB,8BAA8B,CAC5C,WAAW,EAAE,MAAM,GAClB,MAAM,GAAG,SAAS,CAKpB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,OAAO,EACf,WAAW,EAAE,MAAM,GAClB,MAAM,GAAG,SAAS,CAapB"}
+{"version":3,"file":"liquidation.d.ts","sourceRoot":"","sources":["../../../src/utils/liquidation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AASH,OAAO,EAAE,KAAK,aAAa,EAAkB,MAAM,mBAAmB,CAAA;AAEtE;;;;;;;;;GASG;AACH,wBAAgB,8BAA8B,CAC5C,WAAW,EAAE,MAAM,GAClB,aAAa,CAQf;AAED,cAAc;AACd,eAAO,MAAM,kCAAkC,6CAG9C,CAAA;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,OAAO,EACf,WAAW,EAAE,MAAM,GAClB,MAAM,GAAG,SAAS,CAOpB;AAED,cAAc;AACd,eAAO,MAAM,6BAA6B,oGAGzC,CAAA"}

package/dist/types/utils/mapActivity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mapActivity.d.ts","sourceRoot":"","sources":["../../../src/utils/mapActivity.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,aAAa,EAQnB,MAAM,iBAAiB,CAAA;AACxB,OAAO,KAAK,EACV,YAAY,EAIZ,eAAe,EACf,mBAAmB,EACnB,aAAa,EAGd,MAAM,mBAAmB,CAAA;AAG1B,OAAO,KAAK,EAEV,eAAe,EACf,cAAc,EACd,UAAU,EACX,MAAM,mBAAmB,CAAA;AA4D1B;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GACzB,OAAO,cAAc,EACrB,aAAa,MAAM,EACnB,gBAAgB,MAAM,EACtB,eAAe,aAAa,EAC5B,eAAe,CAAC,IAAI,EAAE,MAAM,KAAK,aAAa,GAAG,SAAS,KACzD,YAAY,GAAG,IAwMjB,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,GAC7B,OAAO,eAAe,EACtB,aAAa,MAAM,EACnB,eAAe,CAAC,IAAI,EAAE,MAAM,KAAK,aAAa,GAAG,SAAS,KACzD,eAAe,GAAG,IAoBpB,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,GAC9B,OAAO,UAAU,EAAE,EACnB,aAAa,MAAM,EACnB,gBAAgB,MAAM,EACtB,eAAe,CAAC,IAAI,EAAE,MAAM,KAAK,aAAa,GAAG,SAAS,EAC1D,cAAc,WAAW,CAAC,MAAM,CAAC,KAChC,mBAAmB,EAwDrB,CAAA"}
+{"version":3,"file":"mapActivity.d.ts","sourceRoot":"","sources":["../../../src/utils/mapActivity.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,aAAa,EAQnB,MAAM,iBAAiB,CAAA;AACxB,OAAO,KAAK,EACV,YAAY,EAIZ,eAAe,EACf,mBAAmB,EACnB,aAAa,EAGd,MAAM,mBAAmB,CAAA;AAG1B,OAAO,KAAK,EAEV,eAAe,EACf,cAAc,EACd,UAAU,EACX,MAAM,mBAAmB,CAAA;AA4D1B;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GACzB,OAAO,cAAc,EACrB,aAAa,MAAM,EACnB,gBAAgB,MAAM,EACtB,eAAe,aAAa,EAC5B,eAAe,CAAC,IAAI,EAAE,MAAM,KAAK,aAAa,GAAG,SAAS,KACzD,YAAY,GAAG,IA0MjB,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,GAC7B,OAAO,eAAe,EACtB,aAAa,MAAM,EACnB,eAAe,CAAC,IAAI,EAAE,MAAM,KAAK,aAAa,GAAG,SAAS,KACzD,eAAe,GAAG,IAsBpB,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,GAC9B,OAAO,UAAU,EAAE,EACnB,aAAa,MAAM,EACnB,gBAAgB,MAAM,EACtB,eAAe,CAAC,IAAI,EAAE,MAAM,KAAK,aAAa,GAAG,SAAS,EAC1D,cAAc,WAAW,CAAC,MAAM,CAAC,KAChC,mBAAmB,EA0DrB,CAAA"}

package/dist/types/utils/mapFill.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mapFill.d.ts","sourceRoot":"","sources":["../../../src/utils/mapFill.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,EAIzB,MAAM,iBAAiB,CAAA;AACxB,OAAO,KAAK,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAQ5D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAGnD,0FAA0F;AAC1F,OAAO,EAAE,wBAAwB,EAAE,CAAA;AAEnC;;;;;GAKG;AACH,eAAO,MAAM,OAAO,GAClB,MAAM,UAAU,EAChB,QAAQ,aAAa,KACpB,IAAI,GAAG,SA+CT,CAAA"}
+{"version":3,"file":"mapFill.d.ts","sourceRoot":"","sources":["../../../src/utils/mapFill.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,EAIzB,MAAM,iBAAiB,CAAA;AACxB,OAAO,KAAK,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAQ5D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAGnD,0FAA0F;AAC1F,OAAO,EAAE,wBAAwB,EAAE,CAAA;AAEnC;;;;;GAKG;AACH,eAAO,MAAM,OAAO,GAClB,MAAM,UAAU,EAChB,QAAQ,aAAa,KACpB,IAAI,GAAG,SAkDT,CAAA"}

package/dist/types/utils/mapMarket.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mapMarket.d.ts","sourceRoot":"","sources":["../../../src/utils/mapMarket.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAGpD,OAAO,KAAK,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAqC7E;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,GACpB,UAAU,cAAc,EACxB,YAAY,MAAM,EAClB,qBAAqB,oBAAoB,KACxC,WAuBD,CAAA"}
+{"version":3,"file":"mapMarket.d.ts","sourceRoot":"","sources":["../../../src/utils/mapMarket.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAGpD,OAAO,KAAK,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAqC7E;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,GACpB,UAAU,cAAc,EACxB,YAAY,MAAM,EAClB,qBAAqB,oBAAoB,KACxC,WAyBD,CAAA"}

package/dist/types/utils/mapOrder.d.ts

@@ -1,3 +1,4 @@
+import { type MarketRegistry } from '@lifi/perps-sdk';
 import type { MarketDisplay, Order } from '@lifi/perps-types';
 import { OrderStatus, OrderType } from '@lifi/perps-types';
 import type { HlFrontendOpenOrder, HlOrderDetail, HlTwapHistoryEntry } from '../types/index.js';
@@ -7,6 +8,12 @@ export type HlOrderLike = HlFrontendOpenOrder | HlOrderDetail['order'];
 export declare const mapOrderType: (orderType: string) => Exclude<OrderType, OrderType.TWAP>;
 /** Translate venue lifecycle statuses; unknown statuses are errors. */
 export declare const mapOrderStatus: (status: string) => OrderStatus;
+/**
+ * Map one venue row, or drop it. An outcome market identity, a coin the backend
+ * market list does not hold, and a row the mapper rejects each drop only their
+ * own row; each distinct mapper message warns once.
+ */
+export declare const mapOrderRow: (coin: string, registry: MarketRegistry | undefined, map: (market: MarketDisplay) => Order | undefined) => Order | undefined;
 /**
  * Normalize regular, trigger, and TWAP rows through one lifecycle model. A row
  * whose filled or remaining size or timestamp cannot be derived gives `undefined`.

package/dist/types/utils/mapOrder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mapOrder.d.ts","sourceRoot":"","sources":["../../../src/utils/mapOrder.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EACV,aAAa,EACb,KAAK,EAGN,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAEL,WAAW,EACX,SAAS,EAGV,MAAM,mBAAmB,CAAA;AAE1B,OAAO,KAAK,EACV,mBAAmB,EACnB,aAAa,EACb,kBAAkB,EACnB,MAAM,mBAAmB,CAAA;AAG1B,4EAA4E;AAC5E,MAAM,MAAM,WAAW,GAAG,mBAAmB,GAAG,aAAa,CAAC,OAAO,CAAC,CAAA;AAEtE,gFAAgF;AAChF,eAAO,MAAM,YAAY,GACvB,WAAW,MAAM,KAChB,OAAO,CAAC,SAAS,EAAE,SAAS,CAAC,IAAI,CAiBnC,CAAA;AAED,uEAAuE;AACvE,eAAO,MAAM,cAAc,GAAI,QAAQ,MAAM,KAAG,WAuC/C,CAAA;AAqBD;;;GAGG;AACH,eAAO,MAAM,QAAQ,GACnB,KAAK,WAAW,GAAG,aAAa,GAAG,kBAAkB,EACrD,QAAQ,aAAa,EACrB,gBAAgB,MAAM,KACrB,KAAK,GAAG,SAmKV,CAAA"}
+{"version":3,"file":"mapOrder.d.ts","sourceRoot":"","sources":["../../../src/utils/mapOrder.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,cAAc,EAQpB,MAAM,iBAAiB,CAAA;AACxB,OAAO,KAAK,EACV,aAAa,EACb,KAAK,EAGN,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAEL,WAAW,EACX,SAAS,EAGV,MAAM,mBAAmB,CAAA;AAE1B,OAAO,KAAK,EACV,mBAAmB,EACnB,aAAa,EACb,kBAAkB,EACnB,MAAM,mBAAmB,CAAA;AAI1B,4EAA4E;AAC5E,MAAM,MAAM,WAAW,GAAG,mBAAmB,GAAG,aAAa,CAAC,OAAO,CAAC,CAAA;AAEtE,gFAAgF;AAChF,eAAO,MAAM,YAAY,GACvB,WAAW,MAAM,KAChB,OAAO,CAAC,SAAS,EAAE,SAAS,CAAC,IAAI,CAiBnC,CAAA;AAED,uEAAuE;AACvE,eAAO,MAAM,cAAc,GAAI,QAAQ,MAAM,KAAG,WAuC/C,CAAA;AAaD;;;;GAIG;AACH,eAAO,MAAM,WAAW,GACtB,MAAM,MAAM,EACZ,UAAU,cAAc,GAAG,SAAS,EACpC,KAAK,CAAC,MAAM,EAAE,aAAa,KAAK,KAAK,GAAG,SAAS,KAChD,KAAK,GAAG,SAkBV,CAAA;AAQD;;;GAGG;AACH,eAAO,MAAM,QAAQ,GACnB,KAAK,WAAW,GAAG,aAAa,GAAG,kBAAkB,EACrD,QAAQ,aAAa,EACrB,gBAAgB,MAAM,KACrB,KAAK,GAAG,SAgKV,CAAA"}

package/dist/types/utils/mapPosition.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mapPosition.d.ts","sourceRoot":"","sources":["../../../src/utils/mapPosition.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAGrE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AASxD;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,GAAI,IAAI,eAAe,KAAG,OACP,CAAA;AAEnD;;;;;;;;;GASG;AACH,eAAO,MAAM,WAAW,GACtB,IAAI,eAAe,EACnB,QAAQ,kBAAkB,KACzB,QAAQ,GAAG,SAsDb,CAAA"}
+{"version":3,"file":"mapPosition.d.ts","sourceRoot":"","sources":["../../../src/utils/mapPosition.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAGrE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AAaxD;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,GAAI,IAAI,eAAe,KAAG,OACP,CAAA;AAEnD;;;;;;;;;GASG;AACH,eAAO,MAAM,WAAW,GACtB,IAAI,eAAe,EACnB,QAAQ,kBAAkB,KACzB,QAAQ,GAAG,SAsDb,CAAA"}

package/dist/types/utils/spotBalance.d.ts

@@ -11,9 +11,10 @@ export declare const spotPriceById: (markets: readonly Market[], priceByMarketId
  * Convert a Hyperliquid spot balance's numeric token index into an SDK asset.
  * The balance payload has no `fullName`, so logo resolution uses the base
  * `_spot` URI rule rather than Unit-underlying lookup.
+ * @param registered - The registry `Asset` with the same `id`; only its `decimals` is copied.
  * @public
  */
-export declare const spotAssetFromToken: (b: HlSpotBalance) => Asset;
+export declare const spotAssetFromToken: (b: HlSpotBalance, registered?: Asset) => Asset;
 /** Assemble a typed spot {@link Balance}; `total` is native token units and its unit price and USD value use `priceById`. @public */
 export declare const spotBalance: (asset: Asset, total: DecimalString, priceById: ReadonlyMap<string, DecimalString>) => Balance;
 //# sourceMappingURL=spotBalance.d.ts.map

package/dist/types/utils/spotBalance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"spotBalance.d.ts","sourceRoot":"","sources":["../../../src/utils/spotBalance.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAE9E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAItD;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GACxB,SAAS,SAAS,MAAM,EAAE,EAC1B,iBAAiB,WAAW,CAAC,MAAM,EAAE,aAAa,CAAC,KAClD,GAAG,CAAC,MAAM,EAAE,aAAa,CAc3B,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAAI,GAAG,aAAa,KAAG,KAIpD,CAAA;AAEF,qIAAqI;AACrI,eAAO,MAAM,WAAW,GACtB,OAAO,KAAK,EACZ,OAAO,aAAa,EACpB,WAAW,WAAW,CAAC,MAAM,EAAE,aAAa,CAAC,KAC5C,OAUF,CAAA"}
+{"version":3,"file":"spotBalance.d.ts","sourceRoot":"","sources":["../../../src/utils/spotBalance.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAE9E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAItD;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GACxB,SAAS,SAAS,MAAM,EAAE,EAC1B,iBAAiB,WAAW,CAAC,MAAM,EAAE,aAAa,CAAC,KAClD,GAAG,CAAC,MAAM,EAAE,aAAa,CAc3B,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,GAC7B,GAAG,aAAa,EAChB,aAAa,KAAK,KACjB,KAOD,CAAA;AAEF,qIAAqI;AACrI,eAAO,MAAM,WAAW,GACtB,OAAO,KAAK,EACZ,OAAO,aAAa,EACpB,WAAW,WAAW,CAAC,MAAM,EAAE,aAAa,CAAC,KAC5C,OAUF,CAAA"}

package/dist/types/utils/venueTotals.d.ts

@@ -19,13 +19,9 @@ export declare const perpsTotals: (dexStates: readonly DexMarginSummary[]) => {
     marginUsed: DecimalString;
 };
 /**
- * Sum the unrealized PnL of every position, in quote-asset units.
+ * Sum the unrealized PnL of every position, in quote-asset units. A term that
+ * does not match the decimal pattern adds nothing and warns once.
  * @public
  */
 export declare const sumUnrealizedPnl: (positions: readonly Position[]) => DecimalString;
-/**
- * Sum every term, or `undefined` with a warning when any term is not a
- * decimal string. A bad term never gives a partial sum.
- */
-export declare const safeSumDecimalStrings: (terms: readonly string[]) => DecimalString | undefined;
 //# sourceMappingURL=venueTotals.d.ts.map

package/dist/types/utils/venueTotals.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"venueTotals.d.ts","sourceRoot":"","sources":["../../../src/utils/venueTotals.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,aAAa,EACb,wBAAwB,EACxB,QAAQ,EACT,MAAM,mBAAmB,CAAA;AAG1B;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,aAAa,CAAC,EAAE,wBAAwB,CAAA;CACzC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,GACtB,WAAW,SAAS,gBAAgB,EAAE,KACrC;IAAE,YAAY,EAAE,aAAa,CAAC;IAAC,UAAU,EAAE,aAAa,CAAA;CAyB1D,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,gBAAgB,GAC3B,WAAW,SAAS,QAAQ,EAAE,KAC7B,aAYA,CAAA;AAEH;;;GAGG;AACH,eAAO,MAAM,qBAAqB,GAChC,OAAO,SAAS,MAAM,EAAE,KACvB,aAAa,GAAG,SAKhB,CAAA"}
+{"version":3,"file":"venueTotals.d.ts","sourceRoot":"","sources":["../../../src/utils/venueTotals.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EACV,aAAa,EACb,wBAAwB,EACxB,QAAQ,EACT,MAAM,mBAAmB,CAAA;AAG1B;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,aAAa,CAAC,EAAE,wBAAwB,CAAA;CACzC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,GACtB,WAAW,SAAS,gBAAgB,EAAE,KACrC;IAAE,YAAY,EAAE,aAAa,CAAC;IAAC,UAAU,EAAE,aAAa,CAAA;CAyB1D,CAAA;AAID;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,GAC3B,WAAW,SAAS,QAAQ,EAAE,KAC7B,aAaF,CAAA"}

package/dist/types/utils/withdrawableBalances.d.ts

@@ -11,8 +11,8 @@ import type { HlAbstractionMode, HlClearinghouseState, HlSpotClearinghouseState
  * @param withdrawalFee - Flat venue fee in quote-asset units, set on every
  *   quote-asset row. Hyperliquid deducts it from the requested amount. Absent
  *   leaves every row without a fee.
- * @throws {PerpsError} `SDKError` when the fee or a venue figure is not a
- * decimal.
+ * @throws {PerpsError} `SDKError` when the fee or a venue figure does not match the
+ * decimal pattern.
  * @public
  */
 export declare const hyperliquidWithdrawableBalances: (abstraction: HlAbstractionMode | null, state: HlClearinghouseState, spotState: HlSpotClearinghouseState, quoteAssetId: string, withdrawalFee?: string) => ProviderWithdrawableBalance[];

package/dist/types/websocket/HyperliquidWsProvider.d.ts

@@ -31,6 +31,7 @@ export declare class HyperliquidWsProvider extends WsProviderBase<object> {
     private readonly clearinghouseRefs;
     private readonly client;
     private readonly registry;
+    private readonly assetRegistry;
     private readonly accountChecksByUser;
     private readonly abstractionByUser;
     private readonly summaryUsers;
@@ -115,7 +116,7 @@ export declare class HyperliquidWsProvider extends WsProviderBase<object> {
     private handleActiveSpotAssetCtx;
     /** Latest mid per `Market.id` across asset-context and fast feeds. */
     /** Latest mid per `Market.id` across asset-context and fast feeds; a mid
-     * that is not a decimal string is left out. */
+     * that does not match the decimal pattern is left out. */
     private mergedMids;
     private orderbookReferencePrice;
     private handleL2Book;
@@ -125,6 +126,7 @@ export declare class HyperliquidWsProvider extends WsProviderBase<object> {
     private handleCandle;
     private handleTrades;
     private handleOrderUpdates;
+    private readOrderDetail;
     private handleUserFills;
     private handleAllDexsClearinghouseState;
     /** Whether the mode's collateral lives per-dex, making the perps-only

package/dist/types/websocket/HyperliquidWsProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"HyperliquidWsProvider.d.ts","sourceRoot":"","sources":["../../../src/websocket/HyperliquidWsProvider.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"HyperliquidWsProvider.d.ts","sourceRoot":"","sources":["../../../src/websocket/HyperliquidWsProvider.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lifi/perps-sdk-provider-hyperliquid",
-  "version": "26.0.0",
+  "version": "27.0.1",
   "description": "Hyperliquid provider plugin for @lifi/perps-sdk",
   "homepage": "https://github.com/lifinance/perps-sdk",
   "bugs": {
@@ -49,10 +49,10 @@
   "dependencies": {
     "big.js": "^7.0.1",
     "viem": "^2.55.18",
-    "@lifi/perps-types": "^21.0.0"
+    "@lifi/perps-types": "^22.0.0"
   },
   "peerDependencies": {
-    "@lifi/perps-sdk": "^24.0.0"
+    "@lifi/perps-sdk": "^25.0.1"
   },
   "publishConfig": {
     "access": "public"

package/src/services/getAccount.ts

@@ -1,10 +1,13 @@
 import {
+  type AssetRegistry,
   calculateTransferable,
+  getAssetRegistry,
   getMarketRegistry,
   getMarketsContext,
   isDecimalStringGreaterThan,
   type ProviderGetAccountParams,
   type SDKRequestOptions,
+  safeAddDecimalStrings,
   subtractDecimalString,
   toPerpsMarketDisplay,
   unknownToDecimalString,
@@ -38,7 +41,6 @@ import {
 } from '../utils/index.js'
 import { hlInfoOptions, infoRequest } from '../utils/infoClient.js'
 import { isOpenAssetPosition, mapPosition } from '../utils/mapPosition.js'
-import { safeSumDecimalStrings } from '../utils/venueTotals.js'
 import { requireAccountExists } from './getAccountExists.js'
 
 /**
@@ -68,7 +70,8 @@ const buildBalances = (
   stateByDex: Map<string, HlClearinghouseState>,
   quoteAssetIds: ReadonlySet<string>,
   priceById: ReadonlyMap<string, DecimalString>,
-  quoteAssetByCategory: Map<string, Asset>
+  quoteAssetByCategory: Map<string, Asset>,
+  assetRegistry: AssetRegistry
 ): BalancePartition => {
   const { balances, collateralBalances } = partitionSpotBalances(
     spotState.balances
@@ -85,7 +88,11 @@ const buildBalances = (
           PROVIDER_KEY
         )
         return {
-          ...spotBalance(spotAssetFromToken(b), total, priceById),
+          ...spotBalance(
+            spotAssetFromToken(b, assetRegistry.get(String(b.token))),
+            total,
+            priceById
+          ),
           transferable: calculateTransferable(
             subtractDecimalString(total, hold),
             total
@@ -168,6 +175,7 @@ export const getAccount = async (
   const quoteAssetByCategory = new Map(
     markets.map((m) => [m.categoryId, m.quoteAsset])
   )
+  const assetRegistry = getAssetRegistry(client, PROVIDER_KEY)
 
   const [
     feesResult,
@@ -214,6 +222,7 @@ export const getAccount = async (
       )
     ),
     getMarketsContext(client, { provider: PROVIDER_KEY }, options),
+    assetRegistry.sync(),
   ])
 
   const priceById = spotPriceById(
@@ -271,15 +280,16 @@ export const getAccount = async (
     stateByDex,
     quoteAssetIds,
     priceById,
-    quoteAssetByCategory
+    quoteAssetByCategory,
+    assetRegistry
   )
 
-  const marginUsed = safeSumDecimalStrings(
+  const marginUsed = safeAddDecimalStrings(
     dexStates.flatMap(({ marginSummary }) =>
       marginSummary === undefined ? [] : [marginSummary.totalMarginUsed]
     )
   )
-  const unrealizedPnl = safeSumDecimalStrings(
+  const unrealizedPnl = safeAddDecimalStrings(
     positions.map((position) => position.unrealizedPnl)
   )
 

package/src/services/getOrders.ts

@@ -1,14 +1,11 @@
 import {
   ACTIVE_ORDER_STATUSES,
-  createWarnOnce,
   getMarketRegistry,
   isActiveOrderStatus,
-  type MarketRegistry,
-  PerpsError,
   type ProviderGetOrdersParams,
   type SDKRequestOptions,
 } from '@lifi/perps-sdk'
-import type { MarketDisplay, Order, OrdersResponse } from '@lifi/perps-types'
+import type { Order, OrdersResponse } from '@lifi/perps-types'
 import { PROVIDER_KEY } from '../constants.js'
 import type { HyperliquidContext } from '../context.js'
 import type {
@@ -17,48 +14,14 @@ import type {
   HlTwapHistoryEntry,
 } from '../types/index.js'
 import { withExplorerLinks } from '../utils/explorer.js'
-import { assetIsOutcome, mapOrder, perpsDexNames } from '../utils/index.js'
+import { mapOrder, perpsDexNames } from '../utils/index.js'
 import { hlInfoOptions, infoRequest } from '../utils/infoClient.js'
+import { mapOrderRow } from '../utils/mapOrder.js'
 import { requireAccountExists } from './getAccountExists.js'
 
 /** Parameters for a lifecycle-filtered Hyperliquid order read. */
 export type GetOrdersParams = ProviderGetOrdersParams
 
-const warn = createWarnOnce()
-
-const warnOnce = (key: string): void => {
-  warn(key, `[${PROVIDER_KEY}] ${key}`)
-}
-
-/**
- * Map one venue row, or drop it. An outcome market identity, a coin the backend
- * market list does not hold, and a row the mapper rejects each drop only their
- * own row instead of rejecting the whole page; each distinct mapper message
- * warns once.
- */
-const mapRow = (
-  coin: string,
-  registry: MarketRegistry,
-  map: (market: MarketDisplay) => Order | undefined
-): Order | undefined => {
-  if (assetIsOutcome(coin)) {
-    return undefined
-  }
-  const market = registry.get(coin)
-  if (market === undefined) {
-    return undefined
-  }
-  try {
-    return map(market)
-  } catch (error) {
-    if (!(error instanceof PerpsError)) {
-      throw error
-    }
-    warnOnce(`dropped order row: ${error.message}`)
-    return undefined
-  }
-}
-
 /** Read regular, trigger, and TWAP orders from the requested lifecycle feeds. */
 export const getOrders = async (
   { client, apiUrl }: HyperliquidContext,
@@ -127,7 +90,9 @@ export const getOrders = async (
     seenHistorical.add(key)
     keep(
       key,
-      mapRow(detail.order.coin, registry, (market) => mapOrder(detail, market))
+      mapOrderRow(detail.order.coin, registry, (market) =>
+        mapOrder(detail, market)
+      )
     )
   }
   const raw = open.flat()
@@ -138,13 +103,13 @@ export const getOrders = async (
     if (!childIds.has(order.oid)) {
       keep(
         String(order.oid),
-        mapRow(order.coin, registry, (market) => mapOrder(order, market))
+        mapOrderRow(order.coin, registry, (market) => mapOrder(order, market))
       )
     }
     for (const child of order.children ?? []) {
       keep(
         String(child.oid),
-        mapRow(child.coin, registry, (market) =>
+        mapOrderRow(child.coin, registry, (market) =>
           mapOrder(child, market, String(order.oid))
         )
       )
@@ -154,7 +119,7 @@ export const getOrders = async (
   for (const twap of twaps) {
     keep(
       `twap:${twap.twapId}`,
-      mapRow(twap.state.coin, registry, (market) => mapOrder(twap, market))
+      mapOrderRow(twap.state.coin, registry, (market) => mapOrder(twap, market))
     )
   }
   const matching = [...rows.values()].filter(

package/src/services/getPortfolioHistory.ts

@@ -53,13 +53,9 @@ const validSamples = (
 ): [number, DecimalString][] =>
   samples.flatMap(([timestamp, value]): [number, DecimalString][] => {
     if (!Number.isFinite(timestamp)) {
-      warnSkippedVenueRow(
-        PROVIDER_KEY,
-        row,
-        'timestamp',
-        timestamp,
-        'timestamp'
-      )
+      warnSkippedVenueRow(PROVIDER_KEY, row, 'timestamp', timestamp, {
+        expected: 'timestamp',
+      })
       return []
     }
     return [[timestamp, value]]

package/src/utils/index.ts

@@ -27,6 +27,8 @@ export { hlInfoOptions, infoRequest } from './infoClient.js'
 export {
   calculateLiquidationPrice,
   calculateMaintenanceMarginRate,
+  safeCalculateLiquidationPrice,
+  safeCalculateMaintenanceMarginRate,
 } from './liquidation.js'
 export {
   mapFundingActivity,

package/src/utils/liquidation.ts

@@ -13,50 +13,58 @@
  */
 
 import {
+  createSafeFunction,
   divideDecimalString,
+  estimateLiquidationPrice,
   numberToDecimalString,
-  safeEstimateLiquidationPrice,
+  PerpsError,
 } from '@lifi/perps-sdk'
+import { type DecimalString, PerpsErrorCode } from '@lifi/perps-types'
 
 /**
- * Calculate the maintenance margin fraction for a Hyperliquid asset.
- *
- * Maintenance margin is half of the initial margin at max leverage.
+ * Maintenance margin fraction for a Hyperliquid asset: half of the initial
+ * margin at max leverage, `1 / (2 × maxLeverage)`.
  *
  * @param maxLeverage - Maximum leverage for the asset (e.g., 50 for BTC)
- * @returns Maintenance margin fraction (e.g., 0.01 for 50x max leverage),
- *   or undefined if maxLeverage is zero
+ * @returns Maintenance margin fraction (`'0.01'` for 50x max leverage)
+ * @throws {PerpsError} `ValidationError` when `maxLeverage` is not a finite
+ *   number above zero.
  * @public
  */
 export function calculateMaintenanceMarginRate(
   maxLeverage: number
-): number | undefined {
-  if (maxLeverage === 0) {
-    return undefined
+): DecimalString {
+  if (!Number.isFinite(maxLeverage) || maxLeverage <= 0) {
+    throw new PerpsError(
+      PerpsErrorCode.ValidationError,
+      `\`maxLeverage\` must be a finite number above zero, got ${maxLeverage}.`
+    )
   }
-  return 1 / (2 * maxLeverage)
+  return divideDecimalString('1', numberToDecimalString(2 * maxLeverage))
 }
 
+/** @public */
+export const safeCalculateMaintenanceMarginRate = createSafeFunction(
+  'calculateMaintenanceMarginRate',
+  calculateMaintenanceMarginRate
+)
+
 /**
- * Calculate liquidation price using the exact Hyperliquid formula.
- *
- * For isolated margin, new position prediction. For existing positions,
- * prefer Position.liquidationPrice from the API.
+ * Liquidation price of a new isolated position with the exact Hyperliquid
+ * formula. For an existing position, prefer `Position.liquidationPrice` from
+ * the API.
  *
  * Formula derivation (isolated margin, single position):
- *   margin_per_unit        = entryPrice / leverage
- *   maintenance_per_unit   = entryPrice * mmr
- *   margin_available       = margin_per_unit - maintenance_per_unit
- *   liq_price              = entryPrice - side * margin_available / (1 - mmr * side)
+ *   margin_available = entryPrice × (1 / leverage - mmr)
+ *   liq_price        = entryPrice - side × margin_available / (1 - mmr × side)
  *
- * Where mmr = 1 / (2 * maxLeverage).
- *
- * @param entryPrice - Position entry price
- * @param leverage - User-selected leverage (e.g., 10)
- * @param isLong - True if long position, false if short
- * @param maxLeverage - Asset's maximum leverage (e.g., 50 for BTC). Determines
- *   the maintenance margin rate: mmr = 1 / (2 * maxLeverage)
- * @returns Estimated liquidation price, or undefined if inputs are invalid
+ * @param leverage - User-selected leverage (e.g., `'10'`)
+ * @param maxLeverage - Asset's maximum leverage (e.g., 50 for BTC). Sets
+ *   mmr = 1 / (2 × maxLeverage).
+ * @returns The estimate, or `undefined` when `leverage` is at or above
+ *   `2 × maxLeverage`, as {@link estimateLiquidationPrice} documents.
+ * @throws {PerpsError} `ValidationError` when `maxLeverage` is not a finite
+ *   number above zero, or on an input that `estimateLiquidationPrice` rejects.
  * @public
  */
 export function calculateLiquidationPrice(
@@ -65,16 +73,16 @@ export function calculateLiquidationPrice(
   isLong: boolean,
   maxLeverage: number
 ): string | undefined {
-  if (maxLeverage === 0) {
-    return undefined
-  }
-  return safeEstimateLiquidationPrice({
+  return estimateLiquidationPrice({
     entryPrice,
     leverage,
     isLong,
-    maintenanceMarginRate: divideDecimalString(
-      '1',
-      numberToDecimalString(2 * maxLeverage)
-    ),
+    maintenanceMarginRate: calculateMaintenanceMarginRate(maxLeverage),
   })
 }
+
+/** @public */
+export const safeCalculateLiquidationPrice = createSafeFunction(
+  'calculateLiquidationPrice',
+  calculateLiquidationPrice
+)

package/src/utils/mapActivity.ts

@@ -102,7 +102,9 @@ export const mapLedgerEntry = (
   const { delta } = entry
   const timestamp = rowTimestampToIsoStringOrUndefined(entry.time)
   if (timestamp === undefined) {
-    warnSkippedVenueRow(providerKey, 'ledger', 'time', entry.time, 'timestamp')
+    warnSkippedVenueRow(providerKey, 'ledger', 'time', entry.time, {
+      expected: 'timestamp',
+    })
     return null
   }
   const base = { id: entry.hash, provider: providerKey, timestamp }
@@ -322,7 +324,9 @@ export const mapFundingActivity = (
   }
   const timestamp = rowTimestampToIsoStringOrUndefined(entry.time)
   if (timestamp === undefined) {
-    warnSkippedVenueRow(providerKey, 'funding', 'time', entry.time, 'timestamp')
+    warnSkippedVenueRow(providerKey, 'funding', 'time', entry.time, {
+      expected: 'timestamp',
+    })
     return null
   }
   return {
@@ -387,7 +391,9 @@ export const mapLiquidationFills = (
     const time = Math.max(...group.map((fill) => fill.time))
     const timestamp = rowTimestampToIsoStringOrUndefined(time)
     if (timestamp === undefined) {
-      warnSkippedVenueRow(providerKey, 'liquidation', 'time', time, 'timestamp')
+      warnSkippedVenueRow(providerKey, 'liquidation', 'time', time, {
+        expected: 'timestamp',
+      })
       return []
     }
     const closedSize =

package/src/utils/mapFill.ts

@@ -31,7 +31,10 @@ export const mapFill = (
   const size = fill.sz
   const createdAt = rowTimestampToIsoStringOrUndefined(fill.time)
   if (createdAt === undefined) {
-    warnSkippedVenueRow(PROVIDER_KEY, 'fill', 'time', fill.time, 'timestamp')
+    warnSkippedVenueRow(PROVIDER_KEY, 'fill', 'time', fill.time, {
+      marketId: market.id,
+      expected: 'timestamp',
+    })
     return undefined
   }
   // HL charges the builder portion in the same token as the total fee.

package/src/utils/mapMarket.ts

@@ -3,7 +3,7 @@ import type { PerpsMarket } from '@lifi/perps-types'
 import { PositionMarginAdjustment } from '@lifi/perps-types'
 import { PROVIDER_KEY } from '../constants.js'
 import type { HlMaxMarketOrderNtls, HlUniverseItem } from '../types/index.js'
-import { calculateMaintenanceMarginRate } from './liquidation.js'
+import { safeCalculateMaintenanceMarginRate } from './liquidation.js'
 import { coinAsset } from './marketDisplay.js'
 import { getMaxPriceDecimals } from './orderFormatting.js'
 
@@ -72,5 +72,7 @@ export const mapMarket = (
     (universe.marginMode === undefined && universe.onlyIsolated !== true)
       ? PositionMarginAdjustment.ADD_AND_REMOVE
       : PositionMarginAdjustment.ADD_ONLY,
-  maintenanceMarginRate: calculateMaintenanceMarginRate(universe.maxLeverage),
+  maintenanceMarginRate: safeCalculateMaintenanceMarginRate(
+    universe.maxLeverage
+  ),
 })