@lifi/perps-sdk-provider-hyperliquid 0.0.0-preview-c903f1e

package/dist/types/types/ledger.d.ts

@@ -0,0 +1,93 @@
+import type { Address } from 'viem';
+/**
+ * Hyperliquid `spotTransfer` ledger delta. Emitted for transfers of spot
+ * tokens between Hyperliquid accounts. `user` is the sender, `destination`
+ * the recipient; direction is derived at the call site from the queried
+ * address.
+ * @public
+ */
+export type HlSpotTransferDelta = {
+    type: 'spotTransfer';
+    token: string;
+    amount: string;
+    usdcValue: string;
+    user: Address;
+    destination: Address;
+    fee?: string;
+    nativeTokenFee?: string;
+    nonce?: number;
+};
+/**
+ * Hyperliquid ledger delta emitted for the `sendAsset` exchange action. The
+ * wire `type` literal is `'send'` (NOT `'sendAsset'`); the TS name retains
+ * the `SendAsset` prefix to match `HL_PRIMARY_TYPE_SEND_ASSET`.
+ *
+ * - `user` is the sender, `destination` the recipient. For same-user dex
+ *   moves both equal the queried address.
+ * - `sourceDex` / `destinationDex` use `""` for the main USDC perp DEX,
+ *   `"spot"` for spot, or the perp DEX name otherwise.
+ * - `token` is a wire token identifier (e.g. `"USDC"` or `"TOKEN:0x..."`).
+ * - `nonce` is the wire nonce (ms timestamp); always present on `send`
+ *   deltas, unlike `spotTransfer` where it may be null.
+ * @public
+ */
+export type HlSendAssetDelta = {
+    type: 'send';
+    user: Address;
+    destination: Address;
+    sourceDex: string;
+    destinationDex: string;
+    token: string;
+    amount: string;
+    usdcValue: string;
+    fee: string;
+    nativeTokenFee: string;
+    nonce: number;
+    feeToken: string;
+};
+/** @public */
+export type HlLedgerDelta = HlSpotTransferDelta | HlSendAssetDelta | {
+    type: string;
+    usdc?: string;
+    [key: string]: unknown;
+};
+/**
+ * Type guard for `HlSpotTransferDelta` — TypeScript cannot narrow off the
+ * `type` discriminant alone because the catch-all arm of `HlLedgerDelta` has
+ * `type: string` (a supertype of the literal `'spotTransfer'`). Use this at
+ * call sites that need the strongly-typed shape.
+ * @public
+ */
+export declare const isSpotTransferDelta: (delta: HlLedgerDelta) => delta is HlSpotTransferDelta;
+/**
+ * Type guard for `HlSendAssetDelta`. The wire `type` literal is `'send'`;
+ * see `HlSendAssetDelta` for the naming-vs-wire-format rationale. Same
+ * catch-all-arm caveat as `isSpotTransferDelta`.
+ * @public
+ */
+export declare const isSendAssetDelta: (delta: HlLedgerDelta) => delta is HlSendAssetDelta;
+/** @public */
+export type HlLedgerUpdate = {
+    time: number;
+    hash: string;
+    delta: HlLedgerDelta;
+};
+/** @public */
+export type HlUserNonFundingLedgerUpdates = HlLedgerUpdate[];
+/** @public */
+export type HlFundingDelta = {
+    type: 'funding';
+    coin: string;
+    usdc: string;
+    szi: string;
+    fundingRate: string;
+};
+/** @public */
+export type HlFundingUpdate = {
+    time: number;
+    hash: string;
+    delta: HlFundingDelta;
+};
+/** @public */
+export type HlUserFunding = HlFundingUpdate[];
+//# sourceMappingURL=ledger.d.ts.map

package/dist/types/types/ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger.d.ts","sourceRoot":"","sources":["../../../src/types/ledger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAInC;;;;;;GAMG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,IAAI,EAAE,cAAc,CAAA;IACpB,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;IACjB,IAAI,EAAE,OAAO,CAAA;IACb,WAAW,EAAE,OAAO,CAAA;IACpB,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf,CAAA;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,OAAO,CAAA;IACb,WAAW,EAAE,OAAO,CAAA;IACpB,SAAS,EAAE,MAAM,CAAA;IACjB,cAAc,EAAE,MAAM,CAAA;IACtB,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;IACjB,GAAG,EAAE,MAAM,CAAA;IACX,cAAc,EAAE,MAAM,CAAA;IACtB,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;CACjB,CAAA;AAED,cAAc;AACd,MAAM,MAAM,aAAa,GACrB,mBAAmB,GACnB,gBAAgB,GAChB;IACE,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB,CAAA;AAEL;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,GAC9B,OAAO,aAAa,KACnB,KAAK,IAAI,mBAAoD,CAAA;AAEhE;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAC3B,OAAO,aAAa,KACnB,KAAK,IAAI,gBAAyC,CAAA;AAErD,cAAc;AACd,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,aAAa,CAAA;CACrB,CAAA;AAED,cAAc;AACd,MAAM,MAAM,6BAA6B,GAAG,cAAc,EAAE,CAAA;AAE5D,cAAc;AACd,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,EAAE,SAAS,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;IACX,WAAW,EAAE,MAAM,CAAA;CACpB,CAAA;AAED,cAAc;AACd,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,cAAc,CAAA;CACtB,CAAA;AAED,cAAc;AACd,MAAM,MAAM,aAAa,GAAG,eAAe,EAAE,CAAA"}

package/dist/types/types/order.d.ts

@@ -0,0 +1,51 @@
+/** @public */
+export type HlFrontendOpenOrder = {
+    oid: number;
+    coin: string;
+    side: string;
+    sz: string;
+    limitPx: string;
+    orderType: string;
+    origSz: string;
+    reduceOnly: boolean;
+    timestamp: number;
+    isTrigger: boolean;
+    isPositionTpsl: boolean;
+    triggerCondition: string;
+    triggerPx: string;
+    children: HlFrontendOpenOrder[];
+    tif: string | null;
+    cloid: string | null;
+};
+/** @public */
+export type HlFrontendOpenOrders = HlFrontendOpenOrder[];
+/** @public */
+export type HlOrderDetail = {
+    order: {
+        oid: number;
+        coin: string;
+        side: string;
+        sz: string;
+        limitPx: string;
+        orderType: string;
+        origSz: string;
+        reduceOnly: boolean;
+        timestamp: number;
+        tif: string | null;
+        cloid: string | null;
+        triggerCondition: string;
+        triggerPx: string | null;
+    };
+    status: string;
+    statusTimestamp: number;
+};
+/** @public */
+export type HlOrderStatusFound = {
+    status: 'order';
+    order: HlOrderDetail;
+};
+/** @public */
+export type HlOrderStatusResponse = HlOrderStatusFound | {
+    status: 'unknownOid';
+};
+//# sourceMappingURL=order.d.ts.map

package/dist/types/types/order.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"order.d.ts","sourceRoot":"","sources":["../../../src/types/order.ts"],"names":[],"mappings":"AAEA,cAAc;AACd,MAAM,MAAM,mBAAmB,GAAG;IAChC,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,EAAE,EAAE,MAAM,CAAA;IACV,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,OAAO,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,OAAO,CAAA;IAClB,cAAc,EAAE,OAAO,CAAA;IACvB,gBAAgB,EAAE,MAAM,CAAA;IACxB,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,mBAAmB,EAAE,CAAA;IAC/B,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAClB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CACrB,CAAA;AAED,cAAc;AACd,MAAM,MAAM,oBAAoB,GAAG,mBAAmB,EAAE,CAAA;AAExD,cAAc;AACd,MAAM,MAAM,aAAa,GAAG;IAC1B,KAAK,EAAE;QACL,GAAG,EAAE,MAAM,CAAA;QACX,IAAI,EAAE,MAAM,CAAA;QACZ,IAAI,EAAE,MAAM,CAAA;QACZ,EAAE,EAAE,MAAM,CAAA;QACV,OAAO,EAAE,MAAM,CAAA;QACf,SAAS,EAAE,MAAM,CAAA;QACjB,MAAM,EAAE,MAAM,CAAA;QACd,UAAU,EAAE,OAAO,CAAA;QACnB,SAAS,EAAE,MAAM,CAAA;QACjB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;QAClB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;QACpB,gBAAgB,EAAE,MAAM,CAAA;QACxB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;KACzB,CAAA;IACD,MAAM,EAAE,MAAM,CAAA;IACd,eAAe,EAAE,MAAM,CAAA;CACxB,CAAA;AAED,cAAc;AACd,MAAM,MAAM,kBAAkB,GAAG;IAC/B,MAAM,EAAE,OAAO,CAAA;IACf,KAAK,EAAE,aAAa,CAAA;CACrB,CAAA;AAED,cAAc;AACd,MAAM,MAAM,qBAAqB,GAC7B,kBAAkB,GAClB;IAAE,MAAM,EAAE,YAAY,CAAA;CAAE,CAAA"}

package/dist/types/types/ws.d.ts

@@ -0,0 +1,43 @@
+import type { HlClearinghouseState, HlSpotBalance } from './account.js';
+import type { HlAllMids, HlCandle, HlL2Book } from './asset.js';
+import type { HlUserFill } from './fill.js';
+/** @public */
+export type HlWsMessage = {
+    channel: string;
+    data: unknown;
+};
+/** @public */
+export type HlWsAllMidsData = {
+    mids: HlAllMids;
+    dex?: string;
+};
+/** @public */
+export type HlWsL2BookData = HlL2Book & {
+    coin: string;
+};
+/** @public */
+export type HlWsCandleData = HlCandle & {
+    T: number;
+    s: string;
+    i: string;
+    n: number;
+};
+/** @public */
+export type HlWsUserFillsData = {
+    isSnapshot: boolean;
+    user: string;
+    fills: HlUserFill[];
+};
+/** @public */
+export type HlWsAllDexsClearinghouseStateData = {
+    user: string;
+    clearinghouseStates: [string, Pick<HlClearinghouseState, 'assetPositions'>][];
+};
+/** @public */
+export type HlWsSpotStateData = {
+    user: string;
+    spotState: {
+        balances: HlSpotBalance[];
+    };
+};
+//# sourceMappingURL=ws.d.ts.map

package/dist/types/types/ws.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws.d.ts","sourceRoot":"","sources":["../../../src/types/ws.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AACvE,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAC/D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAE3C,cAAc;AACd,MAAM,MAAM,WAAW,GAAG;IACxB,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,OAAO,CAAA;CACd,CAAA;AAED,cAAc;AACd,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,SAAS,CAAA;IACf,GAAG,CAAC,EAAE,MAAM,CAAA;CACb,CAAA;AAED,cAAc;AACd,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAA;AAExD,cAAc;AACd,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG;IACtC,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;CACV,CAAA;AAED,cAAc;AACd,MAAM,MAAM,iBAAiB,GAAG;IAC9B,UAAU,EAAE,OAAO,CAAA;IACnB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,UAAU,EAAE,CAAA;CACpB,CAAA;AAED,cAAc;AACd,MAAM,MAAM,iCAAiC,GAAG;IAC9C,IAAI,EAAE,MAAM,CAAA;IACZ,mBAAmB,EAAE,CAAC,MAAM,EAAE,IAAI,CAAC,oBAAoB,EAAE,gBAAgB,CAAC,CAAC,EAAE,CAAA;CAC9E,CAAA;AAED,cAAc;AACd,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE;QAAE,QAAQ,EAAE,aAAa,EAAE,CAAA;KAAE,CAAA;CACzC,CAAA"}

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

@@ -0,0 +1,20 @@
+/**
+ * Spot asset IDs use the @pairIndex format (e.g. "@230").
+ *
+ * @public
+ */
+export declare const assetIsSpot: (assetId: string) => boolean;
+/**
+ * Calculate the asset ID for a given provider index and asset index.
+ *
+ * Main provider (provider = ''): assetId = indexInProvider
+ * HIP-3 providers (provider = 'xyz'): assetId = 100_000 + perpDexIndex * 10_000 + indexInProvider
+ * @public
+ */
+export declare const calculateAssetId: (providerIndex: number, indexInProvider: number) => number;
+/**
+ * Get the provider index from the given list of provider names.
+ * @public
+ */
+export declare const getProviderIndex: (provider: string, providerNames: string[]) => number;
+//# sourceMappingURL=assetId.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"assetId.d.ts","sourceRoot":"","sources":["../../../src/utils/assetId.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,eAAO,MAAM,WAAW,GAAI,SAAS,MAAM,KAAG,OAAkC,CAAA;AAEhF;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,GAC3B,eAAe,MAAM,EACrB,iBAAiB,MAAM,KACtB,MAKF,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,gBAAgB,GAC3B,UAAU,MAAM,EAChB,eAAe,MAAM,EAAE,KACtB,MAMF,CAAA"}

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

@@ -0,0 +1,15 @@
+export { assetIsSpot, calculateAssetId, getProviderIndex } from './assetId.js';
+export type { InfoRequestOptions } from './infoClient.js';
+export { hlInfoOptions, infoRequest } from './infoClient.js';
+export { calculateLiquidationPrice, calculateMaintenanceMarginRate, } from './liquidation.js';
+export { mapFundingActivity, mapLedgerEntry } from './mapActivity.js';
+export { classifyFillFromPosition, mapFill } from './mapFill.js';
+export { mapMarket } from './mapMarket.js';
+export { mapMarketPrice } from './mapMarketPrice.js';
+export { isTriggerOrder, isTriggerType, mapOpenOrder, mapOrder, mapOrderStatus, mapOrderType, mapStatusReason, mapTriggerOrder, } from './mapOrder.js';
+export { isOpenAssetPosition, mapPosition } from './mapPosition.js';
+export { coinAsset, perpsDexNames } from './marketDisplay.js';
+export { formatOrderPrice, formatOrderSize, getMaxPriceDecimals, } from './orderFormatting.js';
+export { priceStepToAggregation } from './priceStepToAggregation.js';
+export { spotAssetFromToken, spotBalance, spotPriceById, } from './spotBalance.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAC9E,YAAY,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AACzD,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAC5D,OAAO,EACL,yBAAyB,EACzB,8BAA8B,GAC/B,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AACrE,OAAO,EAAE,wBAAwB,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAChE,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,EACL,cAAc,EACd,aAAa,EACb,YAAY,EACZ,QAAQ,EACR,cAAc,EACd,YAAY,EACZ,eAAe,EACf,eAAe,GAChB,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AACnE,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAC7D,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,mBAAmB,GACpB,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAA;AACpE,OAAO,EACL,kBAAkB,EAClB,WAAW,EACX,aAAa,GACd,MAAM,kBAAkB,CAAA"}

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

@@ -0,0 +1,28 @@
+import { type PerpsSDKClient, type ResolvedRetryPolicy, type SDKRequestOptions } from '@lifi/perps-sdk';
+/** @internal */
+export declare const HYPERLIQUID_RETRY_DEFAULTS: ResolvedRetryPolicy;
+/** @public */
+export interface InfoRequestOptions {
+    signal?: AbortSignal;
+    policy?: ResolvedRetryPolicy;
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Resolve the client's retry/fetch config into options for {@link infoRequest}.
+ *
+ * @public
+ */
+export declare const hlInfoOptions: (client: PerpsSDKClient, options?: SDKRequestOptions) => InfoRequestOptions;
+/**
+ * POST to the Hyperliquid `/info` endpoint and return the parsed JSON body.
+ *
+ * Direct-to-venue: no proxy, no AJV validation, no cache. The caller's type
+ * parameter is trusted; consumers should treat the response shape as
+ * upstream-controlled and normalise into `@lifi/perps-types` shapes before
+ * surfacing.
+ *
+ * Non-2xx responses raise a {@link PerpsError} with the Hyperliquid provider key.
+ * @public
+ */
+export declare function infoRequest<T>(apiUrl: string, body: Record<string, unknown>, options?: InfoRequestOptions): Promise<T>;
+//# sourceMappingURL=infoClient.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"infoClient.d.ts","sourceRoot":"","sources":["../../../src/utils/infoClient.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,mBAAmB,EAExB,KAAK,iBAAiB,EACvB,MAAM,iBAAiB,CAAA;AAIxB,gBAAgB;AAChB,eAAO,MAAM,0BAA0B,EAAE,mBAmBxC,CAAA;AAED,cAAc;AACd,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB,MAAM,CAAC,EAAE,mBAAmB,CAAA;IAC5B,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;CACzB;AAED;;;;GAIG;AACH,eAAO,MAAM,aAAa,GACxB,QAAQ,cAAc,EACtB,UAAU,iBAAiB,KAC1B,kBAQD,CAAA;AAEF;;;;;;;;;;GAUG;AACH,wBAAsB,WAAW,CAAC,CAAC,EACjC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,CAAC,CAAC,CAqCZ"}

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

@@ -0,0 +1,48 @@
+/**
+ * Hyperliquid-specific liquidation price calculation.
+ *
+ * Uses the exact formula from Hyperliquid docs:
+ * https://hyperliquid.gitbook.io/hyperliquid-docs/trading/liquidations
+ *
+ * liq_price = price - side * margin_available / position_size / (1 - l * side)
+ *
+ * Where:
+ * - l = 1 / (2 * maxLeverage) (maintenance margin fraction)
+ * - side = 1 (long) or -1 (short)
+ * - margin_available = isolated_margin - maintenance_margin_required
+ */
+/**
+ * Calculate the maintenance margin fraction for a Hyperliquid asset.
+ *
+ * Maintenance margin is half of the initial margin at max leverage.
+ *
+ * @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
+ * @public
+ */
+export declare function calculateMaintenanceMarginRate(maxLeverage: number): number | undefined;
+/**
+ * Calculate liquidation price using the exact Hyperliquid formula.
+ *
+ * For isolated margin, new position prediction. For existing positions,
+ * 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
+ * @public
+ */
+export declare function calculateLiquidationPrice(entryPrice: number, leverage: number, isLong: boolean, maxLeverage: number): number | undefined;
+//# sourceMappingURL=liquidation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"liquidation.d.ts","sourceRoot":"","sources":["../../../src/utils/liquidation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH;;;;;;;;;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,CAWpB"}

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

@@ -0,0 +1,15 @@
+import type { ActivityItem, FundingActivity, MarketDisplay } from '@lifi/perps-types';
+import type { HlFundingUpdate, HlLedgerUpdate } from '../types/index.js';
+/**
+ * Map a Hyperliquid non-funding ledger entry to an ActivityItem.
+ *
+ * Direction for `spotTransfer` and `sendAsset` is derived from
+ * `queriedAddress` matching the delta's `user` (OUT) or `destination` (IN).
+ * Returns null for unsupported delta types and for same-user `sendAsset`
+ * dex moves (where `user === destination === queriedAddress`).
+ * @public
+ */
+export declare const mapLedgerEntry: (entry: HlLedgerUpdate, providerKey: string, queriedAddress: string, resolveMarket: (coin: string) => MarketDisplay) => ActivityItem | null;
+/** @public */
+export declare const mapFundingActivity: (entry: HlFundingUpdate, providerKey: string, resolveMarket: (coin: string) => MarketDisplay) => FundingActivity;
+//# sourceMappingURL=mapActivity.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mapActivity.d.ts","sourceRoot":"","sources":["../../../src/utils/mapActivity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EAEZ,eAAe,EAEf,aAAa,EAGd,MAAM,mBAAmB,CAAA;AAE1B,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAGxE;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,GACzB,OAAO,cAAc,EACrB,aAAa,MAAM,EACnB,gBAAgB,MAAM,EACtB,eAAe,CAAC,IAAI,EAAE,MAAM,KAAK,aAAa,KAC7C,YAAY,GAAG,IA0IjB,CAAA;AAED,cAAc;AACd,eAAO,MAAM,kBAAkB,GAC7B,OAAO,eAAe,EACtB,aAAa,MAAM,EACnB,eAAe,CAAC,IAAI,EAAE,MAAM,KAAK,aAAa,KAC7C,eASD,CAAA"}

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

@@ -0,0 +1,11 @@
+import { classifyFillFromPosition } from '@lifi/perps-sdk';
+import type { Fill, MarketDisplay } from '@lifi/perps-types';
+import type { HlUserFill } from '../types/index.js';
+export { classifyFillFromPosition };
+/**
+ * Spot-ness comes from the resolved market's category, not the coin string —
+ * HL's canonical spot pair 0 is addressed as `PURR/USDC`, not `@0`.
+ * @public
+ */
+export declare const mapFill: (fill: HlUserFill, market: MarketDisplay) => Fill;
+//# sourceMappingURL=mapFill.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mapFill.d.ts","sourceRoot":"","sources":["../../../src/utils/mapFill.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,EAGzB,MAAM,iBAAiB,CAAA;AACxB,OAAO,KAAK,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAS5D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAEnD,OAAO,EAAE,wBAAwB,EAAE,CAAA;AAEnC;;;;GAIG;AACH,eAAO,MAAM,OAAO,GAAI,MAAM,UAAU,EAAE,QAAQ,aAAa,KAAG,IAwBhE,CAAA"}

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

@@ -0,0 +1,12 @@
+import type { PerpsMarket } from '@lifi/perps-types';
+import type { HlUniverseItem } from '../types/index.js';
+/**
+ * Map a Hyperliquid universe entry to a {@link PerpsMarket}'s static instrument
+ * metadata. Live mark/stats fields live on the `/prices` item — see
+ * {@link mapMarketPrice}. `categoryId` is the `Provider.categories[].id` of the
+ * dex the entry was fetched from — known to the caller at fetch time, never
+ * re-derived from the coin string.
+ * @public
+ */
+export declare const mapMarket: (universe: HlUniverseItem, categoryId: string) => PerpsMarket;
+//# sourceMappingURL=mapMarket.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mapMarket.d.ts","sourceRoot":"","sources":["../../../src/utils/mapMarket.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAEpD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAQvD;;;;;;;GAOG;AACH,eAAO,MAAM,SAAS,GACpB,UAAU,cAAc,EACxB,YAAY,MAAM,KACjB,WAWD,CAAA"}

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

@@ -0,0 +1,10 @@
+import type { MarketPrice } from '@lifi/perps-types';
+import type { HlAssetCtx } from '../types/index.js';
+/**
+ * Map a Hyperliquid asset context plus its mid to a {@link MarketPrice} — the
+ * live mark/stats data for the `/prices` item. `mid` is the market mid from
+ * `allMids`, known to the caller; `HlAssetCtx` carries no mid of its own.
+ * @public
+ */
+export declare const mapMarketPrice: (marketId: string, assetCtx: HlAssetCtx, mid: string) => MarketPrice;
+//# sourceMappingURL=mapMarketPrice.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mapMarketPrice.d.ts","sourceRoot":"","sources":["../../../src/utils/mapMarketPrice.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAInD;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GACzB,UAAU,MAAM,EAChB,UAAU,UAAU,EACpB,KAAK,MAAM,KACV,WAiBF,CAAA"}

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

@@ -0,0 +1,49 @@
+import type { MarketDisplay, OpenOrder, Order, TriggerOrder } from '@lifi/perps-types';
+import { OrderStatus, OrderType } from '@lifi/perps-types';
+import type { HlFrontendOpenOrder, HlOrderDetail } from '../types/index.js';
+/**
+ * Map a Hyperliquid orderType string to the OrderType enum.
+ *
+ * @public
+ */
+export declare const mapOrderType: (orderType: string) => OrderType;
+/** @public */
+export declare const isTriggerType: (type: OrderType) => boolean;
+/**
+ * Decide whether a raw Hyperliquid order belongs in the cross-provider
+ * `triggerOrders` bucket. Single source of truth for both the REST
+ * `getOrders` path (`HlFrontendOpenOrder` payload) and the `orderUpdates`
+ * WS handler (`HlOrderDetail.order`, a strict subset).
+ *
+ * Authoritative signals, in order:
+ *   1. `isTrigger` — REST-only boolean Hyperliquid sets on
+ *      `frontendOpenOrders`. Definitive when present.
+ *   2. `isPositionTpsl` — REST-only flag for TP/SL legs attached to a
+ *      position.
+ *   3. `triggerCondition !== 'N/A'` — present on both REST and WS payloads.
+ *      Non-trigger orders carry the literal `'N/A'`.
+ *   4. `triggerPx` non-null and non-zero — present on both. The reliable
+ *      trigger signal on the WS wire when `orderType` lies (HL pushes
+ *      `'Limit'` for a freshly-placed TP/SL until REST refetch lands the
+ *      corrected type).
+ *   5. `orderType` — final fall-back via `isTriggerType`.
+ * @public
+ */
+export declare const isTriggerOrder: (o: HlFrontendOpenOrder | HlOrderDetail["order"]) => boolean;
+/** @public */
+export declare const mapOpenOrder: (o: HlFrontendOpenOrder, market: MarketDisplay) => OpenOrder;
+/** @public */
+export declare const mapTriggerOrder: (o: HlFrontendOpenOrder, market: MarketDisplay) => TriggerOrder;
+/** @public */
+export declare const mapOrderStatus: (status: string) => OrderStatus;
+/**
+ * Map a raw Hyperliquid order status to a short English sentence
+ * describing *why* the order ended in a terminal non-FILLED state. Bare
+ * `canceled`/`cancelled`/`rejected` carry no actionable detail and
+ * return `undefined`; so do non-terminal and unknown values.
+ * @public
+ */
+export declare const mapStatusReason: (status: string) => string | undefined;
+/** @public */
+export declare const mapOrder: (detail: HlOrderDetail, market: MarketDisplay) => Order;
+//# sourceMappingURL=mapOrder.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mapOrder.d.ts","sourceRoot":"","sources":["../../../src/utils/mapOrder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,SAAS,EACT,KAAK,EACL,YAAY,EACb,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAEL,WAAW,EACX,SAAS,EAEV,MAAM,mBAAmB,CAAA;AAC1B,OAAO,KAAK,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAE3E;;;;GAIG;AACH,eAAO,MAAM,YAAY,GAAI,WAAW,MAAM,KAAG,SAehD,CAAA;AAED,cAAc;AACd,eAAO,MAAM,aAAa,GAAI,MAAM,SAAS,KAAG,OAIjB,CAAA;AAE/B;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,cAAc,GACzB,GAAG,mBAAmB,GAAG,aAAa,CAAC,OAAO,CAAC,KAC9C,OAkBF,CAAA;AAED,cAAc;AACd,eAAO,MAAM,YAAY,GACvB,GAAG,mBAAmB,EACtB,QAAQ,aAAa,KACpB,SAaD,CAAA;AAEF,cAAc;AACd,eAAO,MAAM,eAAe,GAC1B,GAAG,mBAAmB,EACtB,QAAQ,aAAa,KACpB,YAcF,CAAA;AAED,cAAc;AACd,eAAO,MAAM,cAAc,GAAI,QAAQ,MAAM,KAAG,WAmB/C,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,GAAI,QAAQ,MAAM,KAAG,MAAM,GAAG,SAuBzD,CAAA;AAeD,cAAc;AACd,eAAO,MAAM,QAAQ,GACnB,QAAQ,aAAa,EACrB,QAAQ,aAAa,KACpB,KAsBF,CAAA"}

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

@@ -0,0 +1,12 @@
+import type { MarketDisplay, Position } from '@lifi/perps-types';
+import type { HlAssetPosition } from '../types/index.js';
+/**
+ * True when the assetPosition has non-zero size. Hyperliquid keeps zero-size
+ * rows in clearinghouse states after a close; both the REST and WS positions
+ * paths drop them so a close surfaces as absence from the open set.
+ * @public
+ */
+export declare const isOpenAssetPosition: (ap: HlAssetPosition) => boolean;
+/** @public */
+export declare const mapPosition: (ap: HlAssetPosition, market: MarketDisplay) => Position;
+//# sourceMappingURL=mapPosition.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mapPosition.d.ts","sourceRoot":"","sources":["../../../src/utils/mapPosition.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAEhE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AAExD;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,GAAI,IAAI,eAAe,KAAG,OAChB,CAAA;AAE1C,cAAc;AACd,eAAO,MAAM,WAAW,GACtB,IAAI,eAAe,EACnB,QAAQ,aAAa,KACpB,QAsBF,CAAA"}

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

@@ -0,0 +1,17 @@
+import type { Asset, Market } from '@lifi/perps-types';
+/**
+ * Synthesise the {@link Asset} for a Hyperliquid wire coin. `id` and `logoURI`
+ * keep the raw coin — the logo CDN is keyed by it, HIP-3 `dex:` prefix
+ * included. `displaySymbol` drops the prefix: the category is carried by
+ * `categoryId`, never by the display string.
+ * @public
+ */
+export declare const coinAsset: (coin: string) => Asset;
+/**
+ * Distinct wire `dex` names to fan `clearinghouseState` / `frontendOpenOrders`
+ * reads across, derived from the backend market list. Spot is excluded (it has
+ * no clearinghouseState); the main perp dex maps to the empty string.
+ * @public
+ */
+export declare const perpsDexNames: (markets: readonly Market[]) => string[];
+//# sourceMappingURL=marketDisplay.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"marketDisplay.d.ts","sourceRoot":"","sources":["../../../src/utils/marketDisplay.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAQtD;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,GAAI,MAAM,MAAM,KAAG,KAKvC,CAAA;AAEF;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GAAI,SAAS,SAAS,MAAM,EAAE,KAAG,MAAM,EAShE,CAAA"}

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

@@ -0,0 +1,50 @@
+/**
+ * Hyperliquid order size and price formatting for exchange submission.
+ *
+ * These encode Hyperliquid-specific order submission rules. Getting size/price
+ * formatting wrong causes rejected orders.
+ *
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/tick-and-lot-size
+ */
+/**
+ * Derive the maximum number of price decimal places for a given asset.
+ *
+ * @param szDecimals - The asset's szDecimals (from market meta)
+ * @param market - Optional market type (e.g. 'spot'). Defaults to perps rules.
+ * @returns Maximum allowed price decimals
+ * @public
+ */
+export declare function getMaxPriceDecimals(szDecimals: number, market?: string): number;
+/**
+ * Format a size value for order submission.
+ *
+ * Per Hyperliquid docs (tick-and-lot-size):
+ * - Size must be rounded to the asset's szDecimals
+ * - Trailing zeroes must be removed for signing
+ *
+ * @param size - The size value to format
+ * @param szDecimals - Number of decimal places allowed for this asset (from meta)
+ * @returns Size as a string with correct precision, no trailing zeros
+ * @public
+ */
+export declare function formatOrderSize(size: number, szDecimals: number): string;
+/**
+ * Format a price value for order submission.
+ *
+ * Per Hyperliquid docs (tick-and-lot-size):
+ * - Maximum 5 significant figures
+ * - Max decimals = MAX_DECIMALS - szDecimals (6 for perps, 8 for spot)
+ * - Integer prices always allowed regardless of significant figures
+ * - Trailing zeroes must be removed for signing
+ *
+ * Rounding is half-up (away from zero at exact halfway) on the true decimal
+ * value, not on the binary float — (1.005).toFixed(2) would give '1.00'.
+ *
+ * @param price - The price value to format
+ * @param szDecimals - The asset's szDecimals (affects max price decimals)
+ * @param market - Optional market type (e.g. 'spot'). Defaults to perps rules.
+ * @returns Price as a string with correct precision, no trailing zeros
+ * @public
+ */
+export declare function formatOrderPrice(price: number, szDecimals: number, market?: string): string;
+//# sourceMappingURL=orderFormatting.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"orderFormatting.d.ts","sourceRoot":"","sources":["../../../src/utils/orderFormatting.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAeH;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,MAAM,GACd,MAAM,CAER;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAOxE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,MAAM,GACd,MAAM,CAYR"}

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

@@ -0,0 +1,20 @@
+/**
+ * Map a desired price `step` to Hyperliquid's server-side aggregation hint
+ * `(nSigFigs, mantissa)` against the order of magnitude of `referencePrice`
+ * (the market's mark price gives the digit count). HL buckets the book to
+ * `nSigFigs` significant figures, so the figures resolving a price to `step`
+ * granularity are `floor(log10(referencePrice)) - floor(log10(step)) + 1`.
+ *
+ * Returns `{}` (full precision) when the step is finer than HL's 5-sig-fig
+ * grid or the inputs are unusable; clamps to {@link HL_MIN_SIG_FIGS} when the
+ * step is coarser than HL's lowest granularity. `mantissa` is emitted only for
+ * a non-power-of-ten step that lands on the 5-sig-fig grid, since HL ignores
+ * it below `nSigFigs === 5`.
+ *
+ * @public
+ */
+export declare function priceStepToAggregation(step: number, referencePrice: number): {
+    nSigFigs?: number;
+    mantissa?: number;
+};
+//# sourceMappingURL=priceStepToAggregation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"priceStepToAggregation.d.ts","sourceRoot":"","sources":["../../../src/utils/priceStepToAggregation.ts"],"names":[],"mappings":"AAiBA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,cAAc,EAAE,MAAM,GACrB;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CAsB1C"}

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

@@ -0,0 +1,18 @@
+import type { Asset, Balance, Market } from '@lifi/perps-types';
+import type { HlSpotBalance } from '../types/index.js';
+/**
+ * USD price keyed by spot token index: each spot market's live USD price
+ * (from `priceByMarketId`, keyed by `Market.id`) under its base-asset id, and
+ * every market's quote-asset id at $1. A spot market absent from
+ * `priceByMarketId` values its token at 0.
+ */
+export declare const spotPriceById: (markets: readonly Market[], priceByMarketId: ReadonlyMap<string, number>) => Map<string, number>;
+/**
+ * The held spot {@link Asset} for an HL balance: the venue token index
+ * (`b.token`) as `Asset.id` — equal to that token's spot `Market.baseAsset.id`
+ * — with display fields derived from the coin.
+ */
+export declare const spotAssetFromToken: (b: HlSpotBalance) => Asset;
+/** Assemble a typed spot {@link Balance} from its resolved asset and raw size. */
+export declare const spotBalance: (asset: Asset, total: string, priceById: Map<string, number>) => Balance;
+//# sourceMappingURL=spotBalance.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"spotBalance.d.ts","sourceRoot":"","sources":["../../../src/utils/spotBalance.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAE/D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAGtD;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GACxB,SAAS,SAAS,MAAM,EAAE,EAC1B,iBAAiB,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,KAC3C,GAAG,CAAC,MAAM,EAAE,MAAM,CAapB,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,GAAI,GAAG,aAAa,KAAG,KAGpD,CAAA;AAEF,kFAAkF;AAClF,eAAO,MAAM,WAAW,GACtB,OAAO,KAAK,EACZ,OAAO,MAAM,EACb,WAAW,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,KAC7B,OAKD,CAAA"}