@lifi/perps-sdk-provider-hyperliquid 5.1.0 → 6.0.1

package/src/HyperliquidProvider.ts

@@ -11,6 +11,7 @@ import {
   type ProviderGetAccountParams,
   type ProviderGetActivityParams,
   type ProviderGetFillsParams,
+  type ProviderGetMarketSettingsParams,
   type ProviderGetOrderParams,
   type ProviderGetOrdersParams,
   type ProviderGetPositionsParams,
@@ -30,6 +31,7 @@ import {
   type ActivitiesResponse,
   type FillsResponse,
   type Market,
+  type MarketSettings,
   type Order,
   type OrdersResponse,
   PerpsErrorCode,
@@ -56,6 +58,7 @@ import { getAccount } from './services/getAccount.js'
 import { getAccountExists } from './services/getAccountExists.js'
 import { getActivity } from './services/getActivity.js'
 import { getFills } from './services/getFills.js'
+import { getMarketSettings } from './services/getMarketSettings.js'
 import { getOrder } from './services/getOrder.js'
 import { getOrders } from './services/getOrders.js'
 import { getPositions } from './services/getPositions.js'
@@ -68,6 +71,7 @@ import type { HlExtraAgents } from './types/index.js'
 import { hlInfoOptions, infoRequest } from './utils/infoClient.js'
 import { calculateLiquidationPrice } from './utils/liquidation.js'
 import { formatOrderPrice, formatOrderSize } from './utils/orderFormatting.js'
+import { positionMarginConstraints } from './utils/transferMargin.js'
 
 /**
  * Options for {@link hyperliquidProvider}.
@@ -97,15 +101,25 @@ export interface HyperliquidProviderOptions {
  * persistence, and revocation. The base {@link PerpsProviderPlugin} contract
  * stays provider-agnostic — this extension is opt-in for callers that
  * explicitly type against it (e.g. to surface a "revoke agent" affordance).
+ * @public
  */
 export interface HyperliquidPerpsProvider extends PerpsProviderPlugin {
-  /** Resolve the agent wallet address, throwing if none has been created. */
+  /**
+   * Resolve the stored agent wallet address for a user.
+   * @throws {PerpsError} With `AgentNotFound` when no agent has been created.
+   */
   getAgentAddress(address: Address): Promise<Address>
-  /** Whether an agent keypair exists for the user address. */
+  /** Return whether a persisted agent keypair exists for the user address. */
   hasAgent(address: Address): Promise<boolean>
-  /** Remove the user's agent keypair (revoke local authorization). */
+  /**
+   * Remove the user's persisted agent keypair and local authorization.
+   * This does not submit an on-chain `APPROVE_AGENT` revocation.
+   */
   removeAgent(address: Address): Promise<void>
-  /** Import an existing agent keypair for the user address. */
+  /**
+   * Validate, persist, and return an existing agent private key for a user.
+   * The returned private key is stored by the configured {@link StorageAdapter}.
+   */
   importAgent(address: Address, privateKey: Hex): Promise<HyperliquidAgent>
 }
 
@@ -288,6 +302,16 @@ export function hyperliquidProvider(
         opts
       ),
 
+    getMarketSettings: (
+      params: ProviderGetMarketSettingsParams,
+      opts?: SDKRequestOptions
+    ): Promise<MarketSettings | undefined> =>
+      getMarketSettings(
+        contextRef.require(),
+        { address: params.address, market: params.market },
+        opts
+      ),
+
     getOrders: (
       params: ProviderGetOrdersParams,
       opts?: SDKRequestOptions
@@ -383,6 +407,8 @@ export function hyperliquidProvider(
         market.maxLeverage
       ),
 
+    positionMarginConstraints,
+
     projectConfig: (
       config: AccountConfig,
       setup: ProviderAction[],

package/src/services/getAccount.ts

@@ -4,6 +4,7 @@ import {
   type ProviderGetAccountParams,
   type SDKRequestOptions,
   stringToFloat,
+  toPerpsMarketDisplay,
 } from '@lifi/perps-sdk'
 import type {
   AccountResponse,
@@ -214,7 +215,12 @@ export const getAccount = async (
   const positions: Position[] = stateResults.flatMap((state) =>
     state.assetPositions
       .filter(isOpenAssetPosition)
-      .map((ap) => mapPosition(ap, registry.require(ap.position.coin)))
+      .map((ap) =>
+        mapPosition(
+          ap,
+          toPerpsMarketDisplay(registry.require(ap.position.coin))
+        )
+      )
   )
 
   const stateByDex = new Map<string, HlClearinghouseState>()

package/src/services/getActivity.ts

@@ -31,11 +31,15 @@ import {
  */
 export interface GetActivityParams {
   address: Address
+  /** Maximum items returned; defaults to 50 and is capped at 200. */
   limit?: number
-  /** `cursor` is a ms-since-epoch upper bound — items with `timestamp < cursor` are returned. */
+  /** Millisecond timestamp cursor; rows strictly older than it are returned. */
   cursor?: string
+  /** Inclusive lower bound in milliseconds since epoch; defaults to 90 days ago. */
   startTime?: number
+  /** Inclusive upper bound in milliseconds since epoch. */
   endTime?: number
+  /** Optional normalized activity-type filter applied after mapping. */
   type?: ActivityType[]
 }
 

package/src/services/getFills.ts

@@ -22,12 +22,13 @@ import { hlInfoOptions, infoRequest } from '../utils/infoClient.js'
  */
 export interface GetFillsParams {
   address: Address
+  /** Maximum items returned; defaults to 50 and is capped at 200. */
   limit?: number
-  /** Opaque pagination cursor from a previous page's `pagination.cursor`. */
+  /** Opaque cursor returned in the previous page's `pagination.cursor`. */
   cursor?: string
-  /** Inclusive lower bound in ms-since-epoch — switches to the `userFillsByTime` endpoint. */
+  /** Inclusive lower bound in milliseconds; selects `userFillsByTime`. */
   startTime?: number
-  /** Inclusive upper bound in ms-since-epoch — switches to the `userFillsByTime` endpoint. */
+  /** Inclusive upper bound in milliseconds; selects `userFillsByTime`. */
   endTime?: number
 }
 

package/src/services/getMarketSettings.ts

@@ -0,0 +1,56 @@
+import type { SDKRequestOptions } from '@lifi/perps-sdk'
+import {
+  MarginMode,
+  type MarketRef,
+  type MarketSettings,
+} from '@lifi/perps-types'
+import type { Address } from 'viem'
+import { SPOT_MARKET_ID } from '../constants.js'
+import type { HyperliquidContext } from '../context.js'
+import type { HlActiveAssetData } from '../types/index.js'
+import { hlInfoOptions, infoRequest } from '../utils/infoClient.js'
+
+/**
+ * Parameters for {@link getMarketSettings}.
+ *
+ * @public
+ */
+export interface GetMarketSettingsParams {
+  address: Address
+  market: MarketRef
+}
+
+/**
+ * The user's venue-stored margin mode and leverage for one perps market,
+ * read from `activeAssetData` — present whether or not a position is open.
+ * @throws {PerpsError} On Hyperliquid REST error, network, or parsing failures.
+ * @public
+ */
+export const getMarketSettings = async (
+  { client, apiUrl }: HyperliquidContext,
+  params: GetMarketSettingsParams,
+  options?: SDKRequestOptions
+): Promise<MarketSettings | undefined> => {
+  // Spot markets carry no leverage state on the venue.
+  if (params.market.categoryId === SPOT_MARKET_ID) {
+    return undefined
+  }
+  const data = await infoRequest<HlActiveAssetData>(
+    apiUrl,
+    {
+      type: 'activeAssetData',
+      user: params.address,
+      coin: params.market.marketId,
+    },
+    hlInfoOptions(client, options)
+  )
+  const leverage = data.leverage
+  if (!leverage) {
+    return undefined
+  }
+  return {
+    marginMode:
+      leverage.type === 'isolated' ? MarginMode.ISOLATED : MarginMode.CROSS,
+    leverage: leverage.value,
+  }
+}

package/src/services/getOrders.ts

@@ -22,8 +22,9 @@ import { hlInfoOptions, infoRequest } from '../utils/infoClient.js'
  */
 export interface GetOrdersParams {
   address: Address
-  /** Optional filter — opaque `Market.id`. */
+  /** Optional filter using the normalized opaque `Market.id`. */
   marketId?: string
+  /** Page-size hint; Hyperliquid returns all open orders in one response. */
   limit?: number
 }
 

package/src/services/getPositions.ts

@@ -1,4 +1,8 @@
-import { getMarketRegistry, type SDKRequestOptions } from '@lifi/perps-sdk'
+import {
+  getMarketRegistry,
+  type SDKRequestOptions,
+  toPerpsMarketDisplay,
+} from '@lifi/perps-sdk'
 import type { PositionsResponse } from '@lifi/perps-types'
 import type { Address } from 'viem'
 import { PROVIDER_KEY } from '../constants.js'
@@ -18,9 +22,9 @@ import { hlInfoOptions, infoRequest } from '../utils/infoClient.js'
  */
 export interface GetPositionsParams {
   address: Address
-  /** Filter to a single opaque `Market.id` (e.g. `'BTC'`, `'xyz:PURR'`). */
+  /** Optional filter using the normalized opaque `Market.id`. */
   marketId?: string
-  /** Page size hint surfaced on the response. Hyperliquid returns all open positions in one call, so pagination is never required. */
+  /** Page-size hint; Hyperliquid returns all open positions in one response. */
   limit?: number
 }
 
@@ -58,7 +62,12 @@ export const getPositions = async (
   let positions = stateResults.flatMap((state) =>
     state.assetPositions
       .filter(isOpenAssetPosition)
-      .map((ap) => mapPosition(ap, registry.require(ap.position.coin)))
+      .map((ap) =>
+        mapPosition(
+          ap,
+          toPerpsMarketDisplay(registry.require(ap.position.coin))
+        )
+      )
   )
 
   if (params.marketId !== undefined) {

package/src/signers/HyperliquidAgentStore.ts

@@ -15,12 +15,11 @@ const STORAGE_PREFIX = 'lifi-perps-agent'
 /**
  * Hyperliquid agent keypair — an EVM keypair the user approves (via
  * `APPROVE_AGENT`) to sign trading actions on their behalf, so each order
- * does not require a wallet prompt.
+ * does not require a wallet prompt. `privateKey` is a 32-byte EVM hex key.
+ * @public
  */
 export interface HyperliquidAgent {
-  /** Agent wallet address. */
   address: Address
-  /** Agent private key. */
   privateKey: Hex
 }
 
@@ -60,6 +59,7 @@ const isHyperliquidAgent = (value: unknown): value is HyperliquidAgent => {
  * fully compromised page — a same-origin script can still drive this store to
  * decrypt. Blast radius is limited to agent trading: fund withdrawal still
  * requires L1 `APPROVE_AGENT` consent that the agent key alone cannot grant.
+ * @public
  */
 export class HyperliquidAgentStore {
   private storage: StorageAdapter

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>[]
 
 /**
@@ -67,6 +110,21 @@ export type HlPreTransferCheck = {
   userExists: boolean
 }
 
+/**
+ * `activeAssetData` info response: the user's live per-asset trading state.
+ * `leverage` reflects the venue-stored setting whether or not a position is
+ * open on the asset.
+ * @public
+ */
+export type HlActiveAssetData = {
+  user: string
+  coin: string
+  leverage: { type: 'cross' | 'isolated'; value: number }
+  maxTradeSzs: [string, string]
+  availableToTrade: [string, string]
+  markPx: string
+}
+
 /**
  * Possible values returned by the `userAbstraction` info endpoint.
  * `null` means abstraction has never been set; `'default'`/`'disabled'` are
@@ -81,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,20 +1,34 @@
 // 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
   maxLeverage: number
   onlyIsolated?: boolean
+  /** Current replacement for deprecated `onlyIsolated`. */
+  marginMode?: 'strictIsolated' | 'noCross'
   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
@@ -23,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
@@ -39,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
@@ -66,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]
@@ -74,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
@@ -89,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[]