@lifi/perps-sdk-provider-hyperliquid 0.2.0-alpha.0

package/src/services/getOrders.ts

@@ -0,0 +1,101 @@
+import { getMarketRegistry, type SDKRequestOptions } from '@lifi/perps-sdk'
+import type { OpenOrder, OrdersResponse, TriggerOrder } from '@lifi/perps-types'
+import type { Address } from 'viem'
+import { PROVIDER_KEY } from '../constants.js'
+import type { HyperliquidContext } from '../context.js'
+import type {
+  HlFrontendOpenOrder,
+  HlFrontendOpenOrders,
+} from '../types/index.js'
+import {
+  isTriggerOrder,
+  mapOpenOrder,
+  mapTriggerOrder,
+  perpsDexNames,
+} from '../utils/index.js'
+import { hlInfoOptions, infoRequest } from '../utils/infoClient.js'
+
+/**
+ * Parameters for {@link getOrders}.
+ *
+ * @public
+ */
+export interface GetOrdersParams {
+  address: Address
+  /** Optional filter — opaque `Market.id`. */
+  marketId?: string
+  limit?: number
+}
+
+/**
+ * Fetch open + trigger orders across every supported perps sub-dex for
+ * `address`, normalised into `OrdersResponse`. Trigger orders that appear as
+ * children of a parent limit order (Hyperliquid's `normalTpsl` flow) are
+ * extracted and surfaced alongside top-level trigger orders. The backend's
+ * enriched asset list supplies the sub-dex fan-out and display fields; only
+ * `frontendOpenOrders` is read direct.
+ * @throws {PerpsError} On Hyperliquid REST error, network, or parsing failures.
+ * @public
+ */
+export const getOrders = async (
+  { client, apiUrl }: HyperliquidContext,
+  params: GetOrdersParams,
+  options?: SDKRequestOptions
+): Promise<OrdersResponse> => {
+  const registry = getMarketRegistry(client, PROVIDER_KEY)
+  const markets = await registry.sync()
+  const infoOpts = hlInfoOptions(client, options)
+
+  const ordersResults = await Promise.all(
+    perpsDexNames(markets).map((name) =>
+      infoRequest<HlFrontendOpenOrders>(
+        apiUrl,
+        {
+          type: 'frontendOpenOrders',
+          user: params.address,
+          ...(name ? { dex: name } : {}),
+        },
+        infoOpts
+      )
+    )
+  )
+
+  const raw: HlFrontendOpenOrder[] = ordersResults.flat()
+
+  const childOids = new Set<number>()
+  for (const o of raw) {
+    for (const child of o.children) {
+      childOids.add(child.oid)
+    }
+  }
+
+  const nonChild = raw.filter((o) => !childOids.has(o.oid))
+
+  let openOrders: OpenOrder[] = nonChild
+    .filter((o) => !isTriggerOrder(o))
+    .map((o) => mapOpenOrder(o, registry.require(o.coin)))
+
+  let triggerOrders: TriggerOrder[] = [
+    ...nonChild
+      .filter((o) => isTriggerOrder(o))
+      .map((o) => mapTriggerOrder(o, registry.require(o.coin))),
+    ...raw
+      .filter((o) => childOids.has(o.oid))
+      .map((o) => mapTriggerOrder(o, registry.require(o.coin))),
+  ]
+
+  if (params.marketId !== undefined) {
+    openOrders = openOrders.filter((o) => o.market.id === params.marketId)
+    triggerOrders = triggerOrders.filter((o) => o.market.id === params.marketId)
+  }
+
+  return {
+    provider: PROVIDER_KEY,
+    openOrders,
+    triggerOrders,
+    pagination: {
+      limit: params.limit ?? openOrders.length + triggerOrders.length,
+      hasMore: false,
+    },
+  }
+}

package/src/services/getPositions.ts

@@ -0,0 +1,76 @@
+import { getMarketRegistry, type SDKRequestOptions } from '@lifi/perps-sdk'
+import type { PositionsResponse } from '@lifi/perps-types'
+import type { Address } from 'viem'
+import { PROVIDER_KEY } from '../constants.js'
+import type { HyperliquidContext } from '../context.js'
+import type { HlClearinghouseState } from '../types/index.js'
+import {
+  isOpenAssetPosition,
+  mapPosition,
+  perpsDexNames,
+} from '../utils/index.js'
+import { hlInfoOptions, infoRequest } from '../utils/infoClient.js'
+
+/**
+ * Parameters for {@link getPositions}.
+ *
+ * @public
+ */
+export interface GetPositionsParams {
+  address: Address
+  /** Filter to a single opaque `Market.id` (e.g. `'BTC'`, `'xyz:PURR'`). */
+  marketId?: string
+  /** Page size hint surfaced on the response. Hyperliquid returns all open positions in one call, so pagination is never required. */
+  limit?: number
+}
+
+/**
+ * Fetch open positions across every supported perps sub-dex for `address`,
+ * normalised into `PositionsResponse`. Zero-size entries are dropped. The
+ * backend's enriched asset list supplies the sub-dex fan-out and display
+ * fields; only `clearinghouseState` is read direct from Hyperliquid.
+ * @throws {PerpsError} On Hyperliquid REST error, network, or parsing failures.
+ * @public
+ */
+export const getPositions = async (
+  { client, apiUrl }: HyperliquidContext,
+  params: GetPositionsParams,
+  options?: SDKRequestOptions
+): Promise<PositionsResponse> => {
+  const registry = getMarketRegistry(client, PROVIDER_KEY)
+  const markets = await registry.sync()
+  const infoOpts = hlInfoOptions(client, options)
+
+  const stateResults = await Promise.all(
+    perpsDexNames(markets).map((name) =>
+      infoRequest<HlClearinghouseState>(
+        apiUrl,
+        {
+          type: 'clearinghouseState',
+          user: params.address,
+          ...(name ? { dex: name } : {}),
+        },
+        infoOpts
+      )
+    )
+  )
+
+  let positions = stateResults.flatMap((state) =>
+    state.assetPositions
+      .filter(isOpenAssetPosition)
+      .map((ap) => mapPosition(ap, registry.require(ap.position.coin)))
+  )
+
+  if (params.marketId !== undefined) {
+    positions = positions.filter((p) => p.market.id === params.marketId)
+  }
+
+  return {
+    provider: PROVIDER_KEY,
+    positions,
+    pagination: {
+      limit: params.limit ?? positions.length,
+      hasMore: false,
+    },
+  }
+}

package/src/signers/HyperliquidAgentStore.ts

@@ -0,0 +1,176 @@
+import {
+  localStorageAdapter,
+  PerpsError,
+  PerpsErrorMessage,
+  parseStoredRecord,
+  type StorageAdapter,
+} from '@lifi/perps-sdk'
+import { PerpsErrorCode } from '@lifi/perps-types'
+import { type Address, type Hex, isAddress, isHex } from 'viem'
+import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts'
+import { PROVIDER_KEY } from '../constants.js'
+
+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.
+ */
+export interface HyperliquidAgent {
+  /** Agent wallet address. */
+  address: Address
+  /** Agent private key. */
+  privateKey: Hex
+}
+
+const isParsablePrivateKey = (value: unknown): value is Hex => {
+  if (!isHex(value)) {
+    return false
+  }
+  try {
+    privateKeyToAccount(value)
+    return true
+  } catch {
+    return false
+  }
+}
+
+const isHyperliquidAgent = (value: unknown): value is HyperliquidAgent => {
+  if (typeof value !== 'object' || value === null) {
+    return false
+  }
+  const { address, privateKey } = value as Record<string, unknown>
+  return (
+    typeof address === 'string' &&
+    isAddress(address) &&
+    isParsablePrivateKey(privateKey)
+  )
+}
+
+/**
+ * Owns the Hyperliquid agent keypair lifecycle: generate, persist, look up,
+ * and revoke. Keyed per user L1 address. Persisted via the injected
+ * {@link StorageAdapter} (browser `localStorage` by default).
+ */
+export class HyperliquidAgentStore {
+  private storage: StorageAdapter
+  private cache: Map<string, HyperliquidAgent> = new Map()
+
+  constructor(storage?: StorageAdapter) {
+    this.storage = storage ?? localStorageAdapter
+  }
+
+  private storageKey(address: Address): string {
+    return `${STORAGE_PREFIX}:${address.toLowerCase()}:${PROVIDER_KEY}`
+  }
+
+  /**
+   * Get the existing agent for a user address.
+   *
+   * @throws {PerpsError} `AgentNotFound` when no agent exists, or
+   * `AgentStorageCorrupt` when a record is present but malformed (so callers
+   * never act on a structurally-invalid keypair, and `getOrCreate` does not
+   * silently overwrite a poisoned-but-recoverable entry).
+   */
+  async get(address: Address): Promise<HyperliquidAgent> {
+    const key = this.storageKey(address)
+
+    const cached = this.cache.get(key)
+    if (cached) {
+      return cached
+    }
+
+    const stored = await this.storage.get(key)
+    const agent = parseStoredRecord(stored, isHyperliquidAgent)
+    if (agent) {
+      this.cache.set(key, agent)
+      return agent
+    }
+
+    const corrupt = stored !== null
+    const error = new PerpsError(
+      PerpsErrorCode.SDKError,
+      corrupt
+        ? PerpsErrorMessage.AgentStorageCorrupt
+        : PerpsErrorMessage.AgentNotFound
+    )
+    error.tool = '@lifi/perps-sdk-provider-hyperliquid'
+    throw error
+  }
+
+  /**
+   * Get the existing agent for a user address, or create and persist one.
+   * Regenerates only on genuine absence; a malformed stored record surfaces
+   * as `AgentStorageCorrupt` rather than being overwritten with a fresh key.
+   */
+  async getOrCreate(address: Address): Promise<HyperliquidAgent> {
+    try {
+      return await this.get(address)
+    } catch (error) {
+      if (
+        error instanceof PerpsError &&
+        error.message !== PerpsErrorMessage.AgentNotFound
+      ) {
+        throw error
+      }
+      const privateKey = generatePrivateKey()
+      const account = privateKeyToAccount(privateKey)
+
+      const agent: HyperliquidAgent = {
+        address: account.address,
+        privateKey,
+      }
+
+      const key = this.storageKey(address)
+      await this.storage.set(key, JSON.stringify(agent))
+      this.cache.set(key, agent)
+
+      return agent
+    }
+  }
+
+  /** Whether an agent exists for the user address. */
+  async has(address: Address): Promise<boolean> {
+    try {
+      await this.get(address)
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  /**
+   * Remove the agent for a user address. Call when the user revokes agent
+   * authorization.
+   */
+  async remove(address: Address): Promise<void> {
+    const key = this.storageKey(address)
+    this.cache.delete(key)
+    await this.storage.remove(key)
+  }
+
+  /**
+   * Import an existing agent keypair (e.g. restoring from backup or pinning a
+   * specific key) and persist it.
+   */
+  async import(address: Address, privateKey: Hex): Promise<HyperliquidAgent> {
+    const account = privateKeyToAccount(privateKey)
+
+    const agent: HyperliquidAgent = {
+      address: account.address,
+      privateKey,
+    }
+
+    const key = this.storageKey(address)
+    await this.storage.set(key, JSON.stringify(agent))
+    this.cache.set(key, agent)
+
+    return agent
+  }
+
+  /** Clear the in-memory cache. Does not remove persisted agents. */
+  clearCache(): void {
+    this.cache.clear()
+  }
+}

package/src/signers/index.ts

@@ -0,0 +1,5 @@
+// biome-ignore-all lint/performance/noBarrelFile: package-internal barrel.
+
+export type { HyperliquidAgent } from './HyperliquidAgentStore.js'
+export { HyperliquidAgentStore } from './HyperliquidAgentStore.js'
+export { hyperliquidSignActions } from './signActions.js'

package/src/signers/signActions.ts

@@ -0,0 +1,78 @@
+import {
+  PerpsError,
+  type SignActionsContext,
+  signTypedData,
+  signTypedDataWithSigner,
+} from '@lifi/perps-sdk'
+import type {
+  ActionStep,
+  Eip712ActionStep,
+  Eip712SignedActionStep,
+  SignedActionStep,
+} from '@lifi/perps-types'
+import { PerpsErrorCode, PerpsSigner, SigningMethod } from '@lifi/perps-types'
+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.
+ */
+export async function hyperliquidSignActions(
+  agentStore: HyperliquidAgentStore,
+  method: SigningMethod,
+  steps: ActionStep[],
+  address: Address,
+  ctx: SignActionsContext | undefined
+): Promise<SignedActionStep[]> {
+  if (method !== SigningMethod.EIP712) {
+    throw new PerpsError(
+      PerpsErrorCode.SDKError,
+      `hyperliquidProvider.signActions: unsupported SigningMethod '${method}'. ` +
+        'Hyperliquid only signs EIP712 actions.'
+    )
+  }
+
+  const sign = ctx?.signers?.includes(PerpsSigner.USER)
+    ? await userWalletSigner(ctx)
+    : await agentSigner(agentStore, address)
+
+  return Promise.all(
+    (steps as Eip712ActionStep[]).map(
+      async (step): Promise<Eip712SignedActionStep> => ({
+        action: step.action,
+        typedData: step.typedData,
+        signature: await sign(step),
+      })
+    )
+  )
+}
+
+type SignStep = (step: Eip712ActionStep) => Promise<Hex>
+
+async function agentSigner(
+  agentStore: HyperliquidAgentStore,
+  address: Address
+): Promise<SignStep> {
+  const agent = await agentStore.get(address)
+  return (step) => signTypedData(agent.privateKey, step.typedData)
+}
+
+function userWalletSigner(ctx: SignActionsContext): Promise<SignStep> {
+  const wallet = ctx.userWallet
+  if (!wallet) {
+    throw new PerpsError(
+      PerpsErrorCode.SDKError,
+      'hyperliquidProvider.signActions: a USER-signed action requires the ' +
+        'end-user wallet. Pass `userWallet` to createPerpsClient or call ' +
+        'setUserWallet(walletClient).'
+    )
+  }
+  return Promise.resolve((step) =>
+    signTypedDataWithSigner(wallet, step.typedData)
+  )
+}

package/src/types/account.ts

@@ -0,0 +1,74 @@
+// Account-level types returned by Hyperliquid `/info`.
+
+/** @public */
+export type HlPosition = {
+  coin: string
+  szi: string
+  entryPx: string
+  positionValue: string
+  liquidationPx: string
+  unrealizedPnl: string
+  marginUsed: string
+  leverage: {
+    type: string
+    value: number
+  }
+}
+
+/** @public */
+export type HlAssetPosition = {
+  position: HlPosition
+}
+
+/** @public */
+export type HlClearinghouseState = {
+  assetPositions: HlAssetPosition[]
+  marginSummary: {
+    accountValue: string
+    totalMarginUsed: string
+  }
+  crossMarginSummary: {
+    accountValue: string
+    totalMarginUsed: string
+  }
+}
+
+/** @public */
+export type HlSpotBalance = {
+  coin: string
+  token: number
+  total: string
+  hold: string
+  entryNtl: string
+}
+
+/** @public */
+export type HlSpotClearinghouseState = {
+  balances: HlSpotBalance[]
+}
+
+/** @public */
+export type HlUserFees = {
+  userAddRate: string
+  userCrossRate: string
+  activeReferralDiscount: string
+}
+
+/** @public */
+export type HlExtraAgents = Record<string, unknown>[]
+
+/**
+ * Possible values returned by the `userAbstraction` info endpoint.
+ * `null` means abstraction has never been set (standard mode).
+ * @public
+ */
+export const HlAbstractionMode = {
+  DISABLED: 'disabled',
+  UNIFIED_ACCOUNT: 'unifiedAccount',
+  PORTFOLIO_MARGIN: 'portfolioMargin',
+  DEX_ABSTRACTION: 'dexAbstraction',
+} as const
+
+/** @public */
+export type HlAbstractionMode =
+  (typeof HlAbstractionMode)[keyof typeof HlAbstractionMode]

package/src/types/action.ts

@@ -0,0 +1,66 @@
+// Hyperliquid `/exchange` request/response shapes + EIP-712 primary types.
+
+/** @public */
+export type HlExchangeRequest = {
+  action: Record<string, unknown>
+  signature: {
+    r: string
+    s: string
+    v: number
+  }
+  nonce: number
+  vaultAddress?: string | null
+}
+
+/** @public */
+export type HlExchangeResponse = {
+  status: string
+  response?:
+    | string
+    | {
+        type: string
+        data?: {
+          statuses?: (
+            | string
+            | { filled: { totalSz: string; avgPx: string; oid: number } }
+            | { resting: { oid: number } }
+            | { waitingForFill: { oid: number } }
+            | { waitingForTrigger: { oid: number } }
+            | { success: true }
+            | { error: string }
+          )[]
+          status?: unknown
+        }
+      }
+}
+
+/** @public */
+export const HL_PRIMARY_TYPE_APPROVE_AGENT =
+  'HyperliquidTransaction:ApproveAgent' as const
+/** @public */
+export const HL_PRIMARY_TYPE_APPROVE_BUILDER_FEE =
+  'HyperliquidTransaction:ApproveBuilderFee' as const
+/** @public */
+export const HL_PRIMARY_TYPE_USER_SET_ABSTRACTION =
+  'HyperliquidTransaction:UserSetAbstraction' as const
+/** @public */
+export const HL_PRIMARY_TYPE_AGENT_SET_ABSTRACTION =
+  'HyperliquidTransaction:AgentSetAbstraction' as const
+/** @public */
+export const HL_PRIMARY_TYPE_WITHDRAW =
+  'HyperliquidTransaction:Withdraw' as const
+/** @public */
+export const HL_PRIMARY_TYPE_SEND_ASSET =
+  'HyperliquidTransaction:SendAsset' as const
+/** @public */
+export const HL_PRIMARY_TYPE_AGENT = 'Agent' as const
+
+/** @public */
+export type HlPrimaryType =
+  | typeof HL_PRIMARY_TYPE_APPROVE_AGENT
+  | typeof HL_PRIMARY_TYPE_APPROVE_BUILDER_FEE
+  | typeof HL_PRIMARY_TYPE_USER_SET_ABSTRACTION
+  | typeof HL_PRIMARY_TYPE_AGENT_SET_ABSTRACTION
+  | typeof HL_PRIMARY_TYPE_WITHDRAW
+  | typeof HL_PRIMARY_TYPE_SEND_ASSET
+  | typeof HL_PRIMARY_TYPE_AGENT

package/src/types/asset.ts

@@ -0,0 +1,96 @@
+// Asset / market metadata returned by Hyperliquid `/info`.
+
+/** @public */
+export type HlUniverseItem = {
+  name: string
+  szDecimals: number
+  maxLeverage: number
+  onlyIsolated?: boolean
+  isDelisted?: boolean
+}
+
+/** @public */
+export type HlMeta = {
+  universe: HlUniverseItem[]
+}
+
+/** @public */
+export type HlAssetCtx = {
+  funding: string
+  openInterest: string
+  dayNtlVlm: string
+  prevDayPx: string
+  markPx: string
+}
+
+/** @public */
+export type HlMetaAndAssetCtxs = [HlMeta, HlAssetCtx[]]
+
+/** @public */
+export type HlUniverse = HlMeta['universe']
+
+/** @public */
+export type HlAllMids = Record<string, string>
+
+/** @public */
+export type HlCandle = {
+  t: number
+  o: string
+  h: string
+  l: string
+  c: string
+  v: string
+}
+
+/** @public */
+export type HlCandleSnapshot = HlCandle[]
+
+/** @public */
+export type HlLevel = {
+  px: string
+  sz: string
+  n: number
+}
+
+/** @public */
+export type HlL2Book = {
+  levels: [HlLevel[], HlLevel[]]
+  time: number
+}
+
+/** @public */
+export type HlPerpDexs = (null | { name: string })[]
+
+/** @public */
+export type HlSpotToken = {
+  name: string
+  index: number
+  tokenId: string
+  szDecimals: number
+}
+
+/** @public */
+export type HlSpotUniverseEntry = {
+  name: string
+  tokens: [number, number]
+  index: number
+  isCanonical: boolean
+}
+
+/** @public */
+export type HlSpotMeta = {
+  tokens: HlSpotToken[]
+  universe: HlSpotUniverseEntry[]
+}
+
+/** @public */
+export type HlSpotAssetCtx = {
+  coin: string
+  prevDayPx: string
+  dayNtlVlm: string
+  markPx: string
+  midPx: string | null
+}
+
+/** @public */
+export type HlSpotMetaAndAssetCtxs = [HlSpotMeta, HlSpotAssetCtx[]]

package/src/types/fill.ts

@@ -0,0 +1,24 @@
+// Fill shapes returned by Hyperliquid `/info`.
+
+/** @public */
+export type HlUserFill = {
+  tid: number
+  oid: number
+  hash?: string
+  coin: string
+  side: string
+  sz: string
+  px: string
+  dir: string
+  fee: string
+  closedPnl: string
+  crossed: boolean
+  time: number
+  startPosition: string
+}
+
+/** @public */
+export type HlUserFills = HlUserFill[]
+
+/** @public */
+export type HlUserFillsByTime = HlUserFill[]