@lifi/perps-sdk-provider-hyperliquid 6.0.0 → 6.0.2

package/src/signers/signActions.ts

@@ -15,12 +15,14 @@ import type { Address, Hex } from 'viem'
 import type { HyperliquidAgentStore } from './HyperliquidAgentStore.js'
 
 /**
- * Sign a batch of EIP-712 action steps. Hyperliquid owns both EIP712 arms and
- * picks WHO signs from the descriptor's `signers` (forwarded on the context):
- *   - `AGENT` → the user's Hyperliquid agent keypair (provisioned + approved
- *     during setup; a missing agent throws).
- *   - `USER` → the end-user's wallet, read from `ctx.userWallet`.
- * Hyperliquid declares no WASM_BLOB / EVM_TX actions, so those schemes reject.
+ * Sign a batch of Hyperliquid EIP-712 action steps. `AGENT` descriptors use
+ * the persisted per-user agent keypair; `USER` descriptors use
+ * `ctx.userWallet`. Other signing methods are rejected because Hyperliquid
+ * declares no WASM_BLOB or EVM_TX action schemes.
+ *
+ * @throws {PerpsError} When the method is unsupported, the required agent is
+ * missing, or a user-signed action has no wallet.
+ * @public
  */
 export async function hyperliquidSignActions(
   agentStore: HyperliquidAgentStore,

package/src/types/account.ts

@@ -1,26 +1,52 @@
 // Account-level types returned by Hyperliquid `/info`.
 
-/** @public */
+/**
+ * Perpetual position payload from Hyperliquid `clearinghouseState`.
+ *
+ * Numeric values are decimal strings in quote-asset units except `szi`,
+ * which is signed size: positive for long and negative for short. `coin` is
+ * the Hyperliquid wire market identifier; `leverage.type` is typically
+ * `'cross'` or `'isolated'`.
+ * @public
+ */
 export type HlPosition = {
+  /** Hyperliquid wire market identifier. */
   coin: string
+  /** Signed position size; positive is long and negative is short. */
   szi: string
+  /** Average entry price as a decimal string. */
   entryPx: string
+  /** Position notional value as a decimal string. */
   positionValue: string
+  /** Estimated liquidation price; may be an empty string when unavailable. */
   liquidationPx: string
+  /** Unrealized PnL in quote-asset units. */
   unrealizedPnl: string
+  /** Margin currently assigned to this position. */
   marginUsed: string
+  /** Leverage mode and numeric leverage multiplier. */
   leverage: {
     type: string
     value: number
   }
 }
 
-/** @public */
+/**
+ * Wrapper for a position in the `assetPositions` array of a clearinghouse
+ * state response.
+ * @public
+ */
 export type HlAssetPosition = {
   position: HlPosition
 }
 
-/** @public */
+/**
+ * Perpetual clearinghouse account state returned by Hyperliquid `/info`.
+ * `assetPositions` includes zero-size rows that callers may discard. Monetary
+ * fields are decimal strings in the account's quote asset; `marginSummary`
+ * covers all positions while `crossMarginSummary` covers cross margin only.
+ * @public
+ */
 export type HlClearinghouseState = {
   assetPositions: HlAssetPosition[]
   marginSummary: {
@@ -33,7 +59,12 @@ export type HlClearinghouseState = {
   }
 }
 
-/** @public */
+/**
+ * One spot balance from Hyperliquid `spotClearinghouseState`.
+ * `token` is the numeric spot token index, and amounts are decimal strings in
+ * the token's native units.
+ * @public
+ */
 export type HlSpotBalance = {
   coin: string
   token: number
@@ -42,19 +73,31 @@ export type HlSpotBalance = {
   entryNtl: string
 }
 
-/** @public */
+/**
+ * Spot clearinghouse state returned by Hyperliquid `/info`.
+ * @public
+ */
 export type HlSpotClearinghouseState = {
   balances: HlSpotBalance[]
 }
 
-/** @public */
+/**
+ * User fee rates returned by Hyperliquid `userFees`.
+ * Rates are decimal fractions represented as strings, not percentage values
+ * (for example, `'0.00045'` is 0.045%).
+ * @public
+ */
 export type HlUserFees = {
   userAddRate: string
   userCrossRate: string
   activeReferralDiscount: string
 }
 
-/** @public */
+/**
+ * Entries returned by Hyperliquid `extraAgents`. The endpoint may add fields
+ * over time, so the provider retains each entry as an open record.
+ * @public
+ */
 export type HlExtraAgents = Record<string, unknown>[]
 
 /**
@@ -96,6 +139,6 @@ export const HlAbstractionMode = {
   DEX_ABSTRACTION: 'dexAbstraction',
 } as const
 
-/** @public */
+/** Union of the exact `userAbstraction` wire values accepted by Hyperliquid. @public */
 export type HlAbstractionMode =
   (typeof HlAbstractionMode)[keyof typeof HlAbstractionMode]

package/src/types/action.ts

@@ -1,6 +1,13 @@
 // Hyperliquid `/exchange` request/response shapes + EIP-712 primary types.
 
-/** @public */
+/**
+ * EIP-712 `/exchange` request sent to Hyperliquid.
+ *
+ * `action` is the provider-specific action object; signature fields are the
+ * hex `r`/`s` values and recovery byte `v`; `nonce` is milliseconds since the
+ * Unix epoch. `vaultAddress` is included only when submitting for a vault.
+ * @public
+ */
 export type HlExchangeRequest = {
   action: Record<string, unknown>
   signature: {
@@ -12,7 +19,14 @@ export type HlExchangeRequest = {
   vaultAddress?: string | null
 }
 
-/** @public */
+/**
+ * Response envelope returned by Hyperliquid `/exchange`.
+ *
+ * A successful response may contain per-order statuses such as `filled`,
+ * `resting`, or `error`; the provider keeps the upstream status strings and
+ * numeric order IDs unchanged.
+ * @public
+ */
 export type HlExchangeResponse = {
   status: string
   response?:
@@ -34,28 +48,32 @@ export type HlExchangeResponse = {
       }
 }
 
-/** @public */
+/** EIP-712 primary type for user approval of a Hyperliquid agent wallet. @public */
 export const HL_PRIMARY_TYPE_APPROVE_AGENT =
   'HyperliquidTransaction:ApproveAgent' as const
-/** @public */
+/** EIP-712 primary type for user approval of an integrator builder fee. @public */
 export const HL_PRIMARY_TYPE_APPROVE_BUILDER_FEE =
   'HyperliquidTransaction:ApproveBuilderFee' as const
-/** @public */
+/** EIP-712 primary type for changing the user's account abstraction mode. @public */
 export const HL_PRIMARY_TYPE_USER_SET_ABSTRACTION =
   'HyperliquidTransaction:UserSetAbstraction' as const
-/** @public */
+/** EIP-712 primary type for an agent wallet changing abstraction mode. @public */
 export const HL_PRIMARY_TYPE_AGENT_SET_ABSTRACTION =
   'HyperliquidTransaction:AgentSetAbstraction' as const
-/** @public */
+/** EIP-712 primary type for withdrawing assets from Hyperliquid. @public */
 export const HL_PRIMARY_TYPE_WITHDRAW =
   'HyperliquidTransaction:Withdraw' as const
-/** @public */
+/** EIP-712 primary type for sending assets between Hyperliquid accounts or DEXes. @public */
 export const HL_PRIMARY_TYPE_SEND_ASSET =
   'HyperliquidTransaction:SendAsset' as const
-/** @public */
+/** EIP-712 primary type used by the agent wallet authorization payload. @public */
 export const HL_PRIMARY_TYPE_AGENT = 'Agent' as const
 
-/** @public */
+/**
+ * Union of EIP-712 primary type names supported by Hyperliquid signing actions.
+ * Values are the exact strings required in the typed-data domain.
+ * @public
+ */
 export type HlPrimaryType =
   | typeof HL_PRIMARY_TYPE_APPROVE_AGENT
   | typeof HL_PRIMARY_TYPE_APPROVE_BUILDER_FEE

package/src/types/asset.ts

@@ -1,6 +1,10 @@
 // Asset / market metadata returned by Hyperliquid `/info`.
 
-/** @public */
+/**
+ * Perpetual market metadata from Hyperliquid `meta.universe`.
+ * `szDecimals` is the lot-size precision; `maxLeverage` is the venue cap.
+ * @public
+ */
 export type HlUniverseItem = {
   name: string
   szDecimals: number
@@ -11,12 +15,20 @@ export type HlUniverseItem = {
   isDelisted?: boolean
 }
 
-/** @public */
+/**
+ * Perpetual metadata envelope returned by the Hyperliquid `meta` info query.
+ * @public
+ */
 export type HlMeta = {
   universe: HlUniverseItem[]
 }
 
-/** @public */
+/**
+ * Live perpetual market context from Hyperliquid `metaAndAssetCtxs`.
+ * Prices, funding, open interest, and volume are decimal strings; `funding`
+ * is a rate and `dayNtlVlm` is 24-hour notional volume.
+ * @public
+ */
 export type HlAssetCtx = {
   funding: string
   openInterest: string
@@ -25,13 +37,21 @@ export type HlAssetCtx = {
   markPx: string
 }
 
-/** @public */
+/**
+ * Tuple returned by `metaAndAssetCtxs`: static universe metadata followed by
+ * one live context per universe entry.
+ * @public
+ */
 export type HlMetaAndAssetCtxs = [HlMeta, HlAssetCtx[]]
 
-/** @public */
+/** Alias for the perpetual universe array in {@link HlMeta}. @public */
 export type HlUniverse = HlMeta['universe']
 
-/** @public */
+/**
+ * OHLCV candle from Hyperliquid's candle feed. `t` is the opening timestamp
+ * in milliseconds; prices and volume are decimal strings.
+ * @public
+ */
 export type HlCandle = {
   t: number
   o: string
@@ -41,26 +61,43 @@ export type HlCandle = {
   v: string
 }
 
-/** @public */
+/** Snapshot array of {@link HlCandle} values, ordered by the upstream feed. @public */
 export type HlCandleSnapshot = HlCandle[]
 
-/** @public */
+/**
+ * One L2 order-book level. `px` is price, `sz` is aggregate size, and `n` is
+ * the number of orders at that price; numeric values are wire strings except
+ * for the order count.
+ * @public
+ */
 export type HlLevel = {
   px: string
   sz: string
   n: number
 }
 
-/** @public */
+/**
+ * L2 order-book snapshot with bid levels at index 0 and ask levels at index 1.
+ * `time` is the snapshot timestamp in milliseconds.
+ * @public
+ */
 export type HlL2Book = {
   levels: [HlLevel[], HlLevel[]]
   time: number
 }
 
-/** @public */
+/**
+ * Perpetual DEX descriptors from Hyperliquid `perpDexs`; `null` represents the
+ * main DEX and named entries represent HIP-3 sub-DEXes.
+ * @public
+ */
 export type HlPerpDexs = (null | { name: string })[]
 
-/** @public */
+/**
+ * Spot token metadata. `index` is the numeric token index used by spot
+ * clearinghouse balances; `tokenId` is the venue's wire identifier.
+ * @public
+ */
 export type HlSpotToken = {
   name: string
   index: number
@@ -68,7 +105,11 @@ export type HlSpotToken = {
   szDecimals: number
 }
 
-/** @public */
+/**
+ * Spot universe entry describing a trading pair. `tokens` contains the two
+ * numeric token indexes used by the pair.
+ * @public
+ */
 export type HlSpotUniverseEntry = {
   name: string
   tokens: [number, number]
@@ -76,13 +117,17 @@ export type HlSpotUniverseEntry = {
   isCanonical: boolean
 }
 
-/** @public */
+/** Spot metadata envelope containing token definitions and trading pairs. @public */
 export type HlSpotMeta = {
   tokens: HlSpotToken[]
   universe: HlSpotUniverseEntry[]
 }
 
-/** @public */
+/**
+ * Live spot token context. Prices and 24-hour volume are decimal strings;
+ * `midPx` is `null` when the venue has no midpoint for the pair.
+ * @public
+ */
 export type HlSpotAssetCtx = {
   coin: string
   prevDayPx: string
@@ -91,5 +136,5 @@ export type HlSpotAssetCtx = {
   midPx: string | null
 }
 
-/** @public */
+/** Tuple returned by the spot metadata/context info query. @public */
 export type HlSpotMetaAndAssetCtxs = [HlSpotMeta, HlSpotAssetCtx[]]

package/src/types/fill.ts

@@ -1,6 +1,12 @@
 // Fill shapes returned by Hyperliquid `/info`.
 
-/** @public */
+/**
+ * One user trade fill returned by Hyperliquid `userFills` or
+ * `userFillsByTime`. Prices, size, fee, PnL, and starting position are decimal
+ * strings; `time` is milliseconds since the Unix epoch and `tid`/`oid` are
+ * numeric trade and order IDs.
+ * @public
+ */
 export type HlUserFill = {
   tid: number
   oid: number
@@ -17,8 +23,8 @@ export type HlUserFill = {
   startPosition: string
 }
 
-/** @public */
+/** All fills returned by the unbounded `userFills` query. @public */
 export type HlUserFills = HlUserFill[]
 
-/** @public */
+/** Fills returned by the time-bounded `userFillsByTime` query. @public */
 export type HlUserFillsByTime = HlUserFill[]

package/src/types/ledger.ts

@@ -50,7 +50,11 @@ export type HlSendAssetDelta = {
   feeToken: string
 }
 
-/** @public */
+/**
+ * Union of known Hyperliquid non-funding ledger deltas plus an open fallback
+ * for endpoint variants the provider does not map.
+ * @public
+ */
 export type HlLedgerDelta =
   | HlSpotTransferDelta
   | HlSendAssetDelta
@@ -81,17 +85,26 @@ export const isSendAssetDelta = (
   delta: HlLedgerDelta
 ): delta is HlSendAssetDelta => delta.type === 'send'
 
-/** @public */
+/**
+ * One timestamped non-funding ledger update. `time` is milliseconds since
+ * epoch and `hash` is the upstream transaction identifier.
+ * @public
+ */
 export type HlLedgerUpdate = {
   time: number
   hash: string
   delta: HlLedgerDelta
 }
 
-/** @public */
+/** Array returned by `userNonFundingLedgerUpdates`. @public */
 export type HlUserNonFundingLedgerUpdates = HlLedgerUpdate[]
 
-/** @public */
+/**
+ * Funding ledger delta returned by Hyperliquid `userFunding`. `usdc` is the
+ * funding payment, `szi` is signed position size, and `fundingRate` is a
+ * decimal fraction; all are decimal strings.
+ * @public
+ */
 export type HlFundingDelta = {
   type: 'funding'
   coin: string
@@ -100,12 +113,17 @@ export type HlFundingDelta = {
   fundingRate: string
 }
 
-/** @public */
+/**
+ * Timestamped funding update. `time` is milliseconds since epoch; `hash` is
+ * always the zero hash — funding is a system ledger event with no venue
+ * transaction behind it.
+ * @public
+ */
 export type HlFundingUpdate = {
   time: number
   hash: string
   delta: HlFundingDelta
 }
 
-/** @public */
+/** Array returned by the `userFunding` info query. @public */
 export type HlUserFunding = HlFundingUpdate[]

package/src/types/order.ts

@@ -1,6 +1,11 @@
 // Order shapes returned by Hyperliquid `/info`.
 
-/** @public */
+/**
+ * Open order payload returned by Hyperliquid `frontendOpenOrders`.
+ * Sizes/prices are decimal strings; timestamps are milliseconds. Trigger
+ * flags and optional `children` describe attached TP/SL orders.
+ * @public
+ */
 export type HlFrontendOpenOrder = {
   oid: number
   coin: string
@@ -20,10 +25,15 @@ export type HlFrontendOpenOrder = {
   cloid: string | null
 }
 
-/** @public */
+/** Array returned by the `frontendOpenOrders` info query. @public */
 export type HlFrontendOpenOrders = HlFrontendOpenOrder[]
 
-/** @public */
+/**
+ * Order detail nested in an `orderStatus` response. `statusTimestamp` is the
+ * last status-change time in milliseconds; `triggerPx` is nullable for orders
+ * without a trigger.
+ * @public
+ */
 export type HlOrderDetail = {
   order: {
     oid: number
@@ -44,13 +54,17 @@ export type HlOrderDetail = {
   statusTimestamp: number
 }
 
-/** @public */
+/** Successful `orderStatus` response containing the requested order. @public */
 export type HlOrderStatusFound = {
   status: 'order'
   order: HlOrderDetail
 }
 
-/** @public */
+/**
+ * Result of `orderStatus`: either a found order or the exact `'unknownOid'`
+ * sentinel when Hyperliquid has no record for the numeric order ID.
+ * @public
+ */
 export type HlOrderStatusResponse =
   | HlOrderStatusFound
   | { status: 'unknownOid' }

package/src/types/ws.ts

@@ -23,7 +23,11 @@ export type HlWsPerpAssetCtx = {
   oraclePx: string
 }
 
-/** @public */
+/**
+ * Partial perp context carried by compressed (`pac`) updates. Omitted fields
+ * are unchanged from the prior context and must be merged by the consumer.
+ * @public
+ */
 export type HlWsPerpAssetCtxPayload = Partial<HlWsPerpAssetCtx>
 
 /**
@@ -44,7 +48,7 @@ export type HlWsAllDexsAssetCtxsData = {
  */
 export type HlWsPacData = [string, HlWsPerpAssetCtxPayload[]][]
 
-/** @public */
+/** Generic Hyperliquid WS envelope; `channel` identifies the subscription and `data` is channel-specific. @public */
 export type HlWsMessage = {
   channel: string
   data: unknown
@@ -61,7 +65,12 @@ export type HlWsFastAssetCtx = {
   midPx?: string | null
 }
 
-/** @public */
+/**
+ * Incremental spot asset context. Hyperliquid may encode numeric fields as
+ * strings or numbers and omits unchanged fields; `midPx: null` means no book
+ * midpoint is available.
+ * @public
+ */
 export type HlWsSpotAssetCtx = {
   dayNtlVlm?: HlWsNumberString
   prevDayPx?: HlWsNumberString
@@ -71,13 +80,13 @@ export type HlWsSpotAssetCtx = {
   circulatingSupply?: HlWsNumberString
 }
 
-/** @public */
+/** Active perp context event keyed by its Hyperliquid wire coin. @public */
 export type HlWsActiveAssetCtxData = {
   coin: string
   ctx: Partial<Record<keyof HlWsPerpAssetCtx, HlWsNumberString | null>>
 }
 
-/** @public */
+/** Active spot context event keyed by its Hyperliquid wire coin. @public */
 export type HlWsActiveSpotAssetCtxData = {
   coin: string
   ctx: HlWsSpotAssetCtx
@@ -90,23 +99,31 @@ export type HlWsActiveSpotAssetCtxData = {
  */
 export type HlWsSacData = Record<string, HlWsSpotAssetCtx>
 
-/** @public */
+/** L2 snapshot envelope with the wire coin attached to {@link HlL2Book}. @public */
 export type HlWsL2BookData = HlL2Book & { coin: string }
 
-/** @public */
+/**
+ * L2 channel payload. `s` is a full snapshot, while `u` is a compressed delta;
+ * `c` carries the checksum/control value when present.
+ * @public
+ */
 export type HlWsL2Data = {
   s?: HlL2Book & { coin: string }
   c?: string
   u?: HlWsCompressedL2Data
 }
 
-/** @public */
+/** One level in a compressed L2 update: `p` is price and `s` is size. @public */
 export type HlWsCompressedL2Level = {
   p: string
   s: string
 }
 
-/** @public */
+/**
+ * Compressed L2 delta. `t` is the update timestamp in milliseconds, `l` holds
+ * bid/ask levels, and optional `r` describes removals.
+ * @public
+ */
 export type HlWsCompressedL2Data = {
   c: string
   t: number
@@ -117,7 +134,11 @@ export type HlWsCompressedL2Data = {
   ]
 }
 
-/** @public */
+/**
+ * Candle event payload. Inherited `t` is candle-open time; `T` is close time,
+ * `s` is the symbol, `i` is interval, and `n` is the trade count.
+ * @public
+ */
 export type HlWsCandleData = HlCandle & {
   T: number
   s: string
@@ -125,7 +146,11 @@ export type HlWsCandleData = HlCandle & {
   n: number
 }
 
-/** @public */
+/**
+ * Public trade event. Prices and size are decimal strings; `time` is
+ * milliseconds since epoch, with optional trade ID and transaction hash.
+ * @public
+ */
 export type HlWsTrade = {
   coin: string
   side: string
@@ -136,14 +161,18 @@ export type HlWsTrade = {
   hash?: string
 }
 
-/** @public */
+/** User fills event; `isSnapshot` distinguishes the initial snapshot from updates. @public */
 export type HlWsUserFillsData = {
   isSnapshot: boolean
   user: string
   fills: HlUserFill[]
 }
 
-/** @public */
+/**
+ * Per-dex clearinghouse event for one user. Each tuple contains a wire DEX name
+ * and the perp positions/equity fields supplied by that DEX.
+ * @public
+ */
 export type HlWsAllDexsClearinghouseStateData = {
   user: string
   clearinghouseStates: [
@@ -152,7 +181,7 @@ export type HlWsAllDexsClearinghouseStateData = {
   ][]
 }
 
-/** @public */
+/** User spot clearinghouse event containing the current spot balances. @public */
 export type HlWsSpotStateData = {
   user: string
   spotState: { balances: HlSpotBalance[] }

package/src/utils/assetId.ts

@@ -1,15 +1,14 @@
 /**
- * Spot asset IDs use the @pairIndex format (e.g. "@230").
- *
+ * Return whether a Hyperliquid asset ID identifies spot (`@<pairIndex>`).
+ * @param assetId - Raw Hyperliquid asset ID.
  * @public
  */
 export const assetIsSpot = (assetId: string): boolean => assetId.startsWith('@')
 
 /**
- * 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
+ * Calculate Hyperliquid's numeric asset ID from a perp DEX index and the
+ * asset's zero-based index within that DEX. The main DEX uses the index
+ * directly; HIP-3 DEXes use `100000 + dexIndex * 10000 + assetIndex`.
  * @public
  */
 export const calculateAssetId = (
@@ -23,7 +22,8 @@ export const calculateAssetId = (
 }
 
 /**
- * Get the provider index from the given list of provider names.
+ * Find a sub-DEX's zero-based index in the names returned by Hyperliquid.
+ * @throws If `provider` is absent from `providerNames`.
  * @public
  */
 export const getProviderIndex = (