@lifi/perps-sdk 0.1.1-alpha.4 → 0.1.1-alpha.40

package/src/realtime/hyperliquid/HyperliquidWsProvider.ts

@@ -1,12 +1,15 @@
-import type { Subscription, SubscriptionEvent } from '@lifi/perps-types'
-import { HistoryItemStatus, OrderSide, OrderType } from '@lifi/perps-types'
+import type {
+  Position,
+  Subscription,
+  SubscriptionEvent,
+} from '@lifi/perps-types'
 import type {
   HlAssetPosition,
   HlOrderDetail,
   HlUserFill,
 } from '@lifi/perps-types/providers/hyperliquid'
 import {
-  mapHistoryItem,
+  mapFill,
   mapOrder,
   mapPosition,
 } from '@lifi/perps-types/providers/hyperliquid'
@@ -15,27 +18,25 @@ import type { SubscriptionListener, WsProvider } from '../types.js'
 import type {
   HlWsAllMidsData,
   HlWsCandleData,
+  HlWsClearinghouseStateData,
   HlWsL2BookData,
   HlWsMessage,
-  HlWsTrade,
+  HlWsSpotClearinghouseStateData,
   HlWsUserFillsData,
-  HlWsWebData2Data,
 } from './types.js'
 
 export class HyperliquidWsProvider implements WsProvider {
   private rws: ReconnectingWebSocket
   private subs = new Map<string, { count: number; payload: object }>()
   private listeners = new Map<string, Set<SubscriptionListener>>()
-  private readonly dexKey: string
-  private readonly assetIdLookup: Map<string, number>
-
-  constructor(
-    wsUrl: string,
-    dexKey: string,
-    assetIdLookup: Map<string, number>
-  ) {
-    this.dexKey = dexKey
-    this.assetIdLookup = assetIdLookup
+  private readonly providerKey: string
+  private readonly subDexes: string[]
+  private positionsBySubDex = new Map<string, Position[]>()
+  private midsBySubDex = new Map<string, Record<string, string>>()
+
+  constructor(wsUrl: string, providerKey: string, subDexes: string[]) {
+    this.providerKey = providerKey
+    this.subDexes = subDexes
     this.rws = new ReconnectingWebSocket(wsUrl)
     this.rws.on('message', (data) => this.handleMessage(data))
     this.rws.on('open', () => this.resubscribeAll())
@@ -46,13 +47,102 @@ export class HyperliquidWsProvider implements WsProvider {
     listener: SubscriptionListener
   ): Promise<() => void> {
     const key = this.toKey(sub)
-    const payload = this.toHlPayload(sub)
 
     if (!this.listeners.has(key)) {
       this.listeners.set(key, new Set())
     }
     this.listeners.get(key)!.add(listener)
 
+    // Prices require multi-sub-dex allMids subscriptions
+    if (sub.channel === 'prices') {
+      const entries = this.getPriceSubEntries()
+
+      for (const { subKey, payload } of entries) {
+        const existing = this.subs.get(subKey)
+        if (existing) {
+          existing.count++
+        } else {
+          this.subs.set(subKey, { count: 1, payload })
+          await this.rws.ready()
+          this.rws.send(
+            JSON.stringify({ method: 'subscribe', subscription: payload })
+          )
+        }
+      }
+
+      return () => {
+        this.listeners.get(key)?.delete(listener)
+        let allRemoved = true
+        for (const { subKey, payload } of entries) {
+          const s = this.subs.get(subKey)
+          if (s) {
+            s.count--
+            if (s.count <= 0) {
+              this.subs.delete(subKey)
+              this.rws.send(
+                JSON.stringify({
+                  method: 'unsubscribe',
+                  subscription: payload,
+                })
+              )
+            } else {
+              allRemoved = false
+            }
+          }
+        }
+        if (allRemoved) {
+          this.listeners.delete(key)
+          this.midsBySubDex.clear()
+        }
+      }
+    }
+
+    // Positions require multi-sub-dex clearinghouseState subscriptions
+    if (sub.channel === 'positions') {
+      const entries = this.getPositionSubEntries(sub.address)
+
+      for (const { subKey, payload } of entries) {
+        const existing = this.subs.get(subKey)
+        if (existing) {
+          existing.count++
+        } else {
+          this.subs.set(subKey, { count: 1, payload })
+          await this.rws.ready()
+          this.rws.send(
+            JSON.stringify({ method: 'subscribe', subscription: payload })
+          )
+        }
+      }
+
+      return () => {
+        this.listeners.get(key)?.delete(listener)
+        let allRemoved = true
+        for (const { subKey, payload } of entries) {
+          const s = this.subs.get(subKey)
+          if (s) {
+            s.count--
+            if (s.count <= 0) {
+              this.subs.delete(subKey)
+              this.rws.send(
+                JSON.stringify({
+                  method: 'unsubscribe',
+                  subscription: payload,
+                })
+              )
+            } else {
+              allRemoved = false
+            }
+          }
+        }
+        if (allRemoved) {
+          this.listeners.delete(key)
+          this.positionsBySubDex.clear()
+        }
+      }
+    }
+
+    // All other channels: single WS subscription per key
+    const payload = this.toHlPayload(sub)
     const existing = this.subs.get(key)
     if (existing) {
       existing.count++
@@ -80,6 +170,37 @@ export class HyperliquidWsProvider implements WsProvider {
     }
   }
 
+  /** Build sub-key + payload pairs for each sub-dex allMids subscription. */
+  private getPriceSubEntries(): Array<{ subKey: string; payload: object }> {
+    return [
+      {
+        subKey: 'allMids:default',
+        payload: { type: 'allMids' },
+      },
+      ...this.subDexes.map((dex) => ({
+        subKey: `allMids:${dex}`,
+        payload: { type: 'allMids', dex },
+      })),
+    ]
+  }
+
+  /** Build sub-key + payload pairs for each sub-dex clearinghouseState subscription. */
+  private getPositionSubEntries(
+    address: string
+  ): Array<{ subKey: string; payload: object }> {
+    const addr = address.toLowerCase()
+    return [
+      {
+        subKey: `positions:${addr}:default`,
+        payload: { type: 'clearinghouseState', user: address },
+      },
+      ...this.subDexes.map((dex) => ({
+        subKey: `positions:${addr}:${dex}`,
+        payload: { type: 'clearinghouseState', user: address, dex },
+      })),
+    ]
+  }
+
   close() {
     this.rws.close()
     this.subs.clear()
@@ -99,36 +220,48 @@ export class HyperliquidWsProvider implements WsProvider {
       case 'prices':
         return 'allMids'
       case 'orderbook':
-        return `l2Book:${sub.symbol}`
-      case 'trades':
-        return `trades:${sub.symbol}`
+        return `l2Book:${sub.assetId}`
       case 'candle':
-        return `candle:${sub.symbol}:${sub.interval}`
+        return `candle:${sub.assetId}:${sub.interval}`
       case 'orderUpdates':
-        return `orderUpdates:${sub.address}`
+        return `orderUpdates:${sub.address.toLowerCase()}`
       case 'fills':
-        return `userFills:${sub.address}`
+        return `userFills:${sub.address.toLowerCase()}`
       case 'positions':
-        return `webData2:${sub.address}`
+        return `positions:${sub.address.toLowerCase()}`
+      case 'spotBalances':
+        return `spotClearinghouseState:${sub.address.toLowerCase()}`
     }
   }
 
   private toHlPayload(sub: Subscription): object {
     switch (sub.channel) {
       case 'prices':
+        // Prices are handled via getPriceSubEntries in subscribe()
+        // and never reach toHlPayload, but TS requires exhaustive cases.
         return { type: 'allMids' }
       case 'orderbook':
-        return { type: 'l2Book', coin: sub.symbol }
-      case 'trades':
-        return { type: 'trades', coin: sub.symbol }
+        return {
+          type: 'l2Book',
+          coin: sub.assetId,
+          ...(sub.depth !== undefined ? { nLevels: sub.depth } : {}),
+        }
       case 'candle':
-        return { type: 'candle', coin: sub.symbol, interval: sub.interval }
+        return {
+          type: 'candle',
+          coin: sub.assetId,
+          interval: sub.interval,
+        }
       case 'orderUpdates':
         return { type: 'orderUpdates', user: sub.address }
       case 'fills':
         return { type: 'userFills', user: sub.address }
       case 'positions':
-        return { type: 'webData2', user: sub.address }
+        // Positions are handled via getPositionSubEntries in subscribe()
+        // and never reach toHlPayload, but TS requires exhaustive cases.
+        return { type: 'clearinghouseState', user: sub.address }
+      case 'spotBalances':
+        return { type: 'spotClearinghouseState', user: sub.address }
     }
   }
 
@@ -174,9 +307,6 @@ export class HyperliquidWsProvider implements WsProvider {
         case 'l2Book':
           this.handleL2Book(msg.data as HlWsL2BookData)
           break
-        case 'trades':
-          this.handleTrades(msg.data as HlWsTrade[])
-          break
         case 'candle':
           this.handleCandle(msg.data as HlWsCandleData)
           break
@@ -186,8 +316,13 @@ export class HyperliquidWsProvider implements WsProvider {
         case 'userFills':
           this.handleUserFills(msg.data as HlWsUserFillsData)
           break
-        case 'webData2':
-          this.handleWebData2(msg.data as HlWsWebData2Data)
+        case 'clearinghouseState':
+          this.handleClearinghouseState(msg.data as HlWsClearinghouseStateData)
+          break
+        case 'spotClearinghouseState':
+          this.handleSpotClearinghouseState(
+            msg.data as HlWsSpotClearinghouseStateData
+          )
           break
       }
     } catch {
@@ -196,15 +331,24 @@ export class HyperliquidWsProvider implements WsProvider {
   }
 
   private handleAllMids(data: HlWsAllMidsData) {
-    this.emit('allMids', { channel: 'prices', data: { prices: data.mids } })
+    const subDexKey = data.dex || 'default'
+    this.midsBySubDex.set(subDexKey, data.mids)
+
+    // Merge all sub-dex mids into a single record
+    const merged: Record<string, string> = {}
+    for (const mids of this.midsBySubDex.values()) {
+      Object.assign(merged, mids)
+    }
+
+    this.emit('allMids', { channel: 'prices', data: merged })
   }
 
   private handleL2Book(data: HlWsL2BookData) {
     this.emit(`l2Book:${data.coin}`, {
       channel: 'orderbook',
       data: {
-        dex: this.dexKey,
-        symbol: data.coin,
+        provider: this.providerKey,
+        assetId: data.coin,
         bids: data.levels[0].map((l) => ({ price: l.px, size: l.sz })),
         asks: data.levels[1].map((l) => ({ price: l.px, size: l.sz })),
         timestamp: data.time,
@@ -212,27 +356,6 @@ export class HyperliquidWsProvider implements WsProvider {
     })
   }
 
-  private handleTrades(data: HlWsTrade[]) {
-    if (data.length === 0) {
-      return
-    }
-    const coin = data[0].coin
-    const items = data.map((t) => ({
-      id: String(t.tid),
-      symbol: t.coin,
-      assetId: this.assetIdLookup.get(t.coin) ?? -1,
-      dex: this.dexKey,
-      side: t.side === 'B' ? OrderSide.BUY : OrderSide.SELL,
-      type: OrderType.MARKET,
-      size: t.sz,
-      price: t.px,
-      status: HistoryItemStatus.FILLED,
-      filledSize: t.sz,
-      createdAt: new Date(t.time).toISOString(),
-    }))
-    this.emit(`trades:${coin}`, { channel: 'trades', data: items })
-  }
-
   private handleCandle(data: HlWsCandleData) {
     this.emit(`candle:${data.s}:${data.i}`, {
       channel: 'candle',
@@ -256,19 +379,35 @@ export class HyperliquidWsProvider implements WsProvider {
   }
 
   private handleUserFills(data: HlWsUserFillsData) {
-    const items = data.fills.map((f) =>
-      mapHistoryItem(f as HlUserFill, this.dexKey, this.assetIdLookup)
-    )
+    const items = data.fills.map((f) => mapFill(f as HlUserFill))
     this.emit(`userFills:${data.user}`, { channel: 'fills', data: items })
   }
 
-  private handleWebData2(data: HlWsWebData2Data) {
+  private handleClearinghouseState(data: HlWsClearinghouseStateData) {
+    const subDexKey = data.dex || 'default'
     const positions = data.clearinghouseState.assetPositions.map((ap) =>
-      mapPosition(ap as HlAssetPosition, this.dexKey, this.assetIdLookup)
+      mapPosition(ap as HlAssetPosition)
     )
-    this.emit(`webData2:${data.user}`, {
+    this.positionsBySubDex.set(subDexKey, positions)
+
+    // Merge all sub-dex positions into a single flat array
+    const merged = [...this.positionsBySubDex.values()].flat()
+
+    this.emit(`positions:${data.user.toLowerCase()}`, {
       channel: 'positions',
-      data: positions,
+      data: merged,
+    })
+  }
+
+  private handleSpotClearinghouseState(data: HlWsSpotClearinghouseStateData) {
+    const balances = data.balances.map((b) => ({
+      coin: b.coin,
+      total: b.total,
+      hold: b.hold,
+    }))
+    this.emit(`spotClearinghouseState:${data.user.toLowerCase()}`, {
+      channel: 'spotBalances',
+      data: balances,
     })
   }
 }

package/src/realtime/hyperliquid/types.ts

@@ -16,19 +16,11 @@ export type HlWsMessage = {
 
 export type HlWsAllMidsData = {
   mids: HlAllMids
+  dex?: string
 }
 
 export type HlWsL2BookData = HlL2Book & { coin: string }
 
-export type HlWsTrade = {
-  coin: string
-  side: string
-  px: string
-  sz: string
-  time: number
-  tid: number
-}
-
 export type HlWsCandleData = HlCandle & {
   T: number
   s: string
@@ -42,7 +34,13 @@ export type HlWsUserFillsData = {
   fills: HlUserFill[]
 }
 
-export type HlWsWebData2Data = {
+export type HlWsClearinghouseStateData = {
+  dex: string
   user: string
   clearinghouseState: Pick<HlClearinghouseState, 'assetPositions'>
 }
+
+export type HlWsSpotClearinghouseStateData = {
+  user: string
+  balances: Array<{ coin: string; total: string; hold: string }>
+}

package/src/services/createAction.ts

@@ -0,0 +1,41 @@
+import type {
+  ActionParamsMap,
+  ActionType,
+  Address,
+  CreateActionResponse,
+} from '@lifi/perps-types'
+import type {
+  PerpsSDKClient,
+  SDKRequestOptions,
+} from '../client/createPerpsClient.js'
+import { request } from '../utils/request.js'
+
+export interface CreateActionParams<T extends ActionType = ActionType> {
+  provider: string
+  address: Address
+  signerAddress?: Address
+  action: T
+  params: ActionParamsMap[T]
+}
+
+export async function createAction<T extends ActionType>(
+  client: PerpsSDKClient,
+  params: CreateActionParams<T>,
+  options?: SDKRequestOptions
+): Promise<CreateActionResponse> {
+  return request<CreateActionResponse>(
+    client.config,
+    `${client.config.apiUrl}/createAction`,
+    {
+      method: 'POST',
+      body: JSON.stringify({
+        provider: params.provider,
+        address: params.address,
+        signerAddress: params.signerAddress,
+        action: params.action,
+        params: params.params,
+      }),
+    },
+    options
+  )
+}

package/src/services/executeAction.ts

@@ -0,0 +1,41 @@
+import type {
+  ActionType,
+  Address,
+  ExecuteActionResponse,
+  SignedActionStep,
+} from '@lifi/perps-types'
+import type {
+  PerpsSDKClient,
+  SDKRequestOptions,
+} from '../client/createPerpsClient.js'
+import { request } from '../utils/request.js'
+
+export interface ExecuteActionParams {
+  provider: string
+  address: Address
+  signerAddress?: Address
+  action: ActionType
+  actions: SignedActionStep[]
+}
+
+export async function executeAction(
+  client: PerpsSDKClient,
+  params: ExecuteActionParams,
+  options?: SDKRequestOptions
+): Promise<ExecuteActionResponse> {
+  return request<ExecuteActionResponse>(
+    client.config,
+    `${client.config.apiUrl}/executeAction`,
+    {
+      method: 'POST',
+      body: JSON.stringify({
+        provider: params.provider,
+        address: params.address,
+        signerAddress: params.signerAddress,
+        action: params.action,
+        actions: params.actions,
+      }),
+    },
+    options
+  )
+}

package/src/services/getAccount.ts

@@ -6,32 +6,32 @@ import type {
 import { buildUrl, request } from '../utils/request.js'
 
 export interface GetAccountParams {
-  /** DEX to get account from (e.g., 'hyperliquid') */
-  dex: string
+  /** Provider to get account from (e.g., 'hyperliquid') */
+  provider: string
   /** Wallet address */
   address: Address
 }
 
 /**
- * Get account information including balances, positions, and open orders.
+ * Get account information including balances and margin details.
+ *
+ * Use {@link getPositions} and {@link getOrders} to fetch positions and orders separately.
  *
  * @param client - The SDK client instance
  * @param params - Request parameters
  * @param options - Request options (e.g., AbortSignal)
  * @returns Account details
- * @throws {HTTPError} On API error responses
+ * @throws {PerpsError} On API error responses
  * @throws {PerpsError} On network or parsing errors
  *
  * @example
  * ```ts
  * const client = createPerpsClient({ integrator: 'my-app' })
  * const account = await getAccount(client, {
- *   dex: 'hyperliquid',
+ *   provider: 'hyperliquid',
  *   address: '0x1234...'
  * })
  * console.log(account.balances) // [{ currency: 'USDC', amount: '10000.00' }]
- * console.log(account.positions) // [{ symbol: 'BTC', side: 'LONG', ... }]
- * console.log(account.openOrders) // [{ id: '123', symbol: 'BTC', ... }]
  * ```
  */
 export async function getAccount(
@@ -40,7 +40,7 @@ export async function getAccount(
   options?: SDKRequestOptions
 ): Promise<AccountResponse> {
   const url = buildUrl(`${client.config.apiUrl}/account`, {
-    dex: params.dex,
+    provider: params.provider,
     address: params.address,
   })
   return request<AccountResponse>(client.config, url, {}, options)

package/src/services/getActivity.ts

@@ -0,0 +1,77 @@
+import type {
+  ActivitiesResponse,
+  ActivityType,
+  Address,
+} from '@lifi/perps-types'
+import type {
+  PerpsSDKClient,
+  SDKRequestOptions,
+} from '../client/createPerpsClient.js'
+import { buildUrl, request } from '../utils/request.js'
+
+export interface GetActivityParams {
+  /** Provider to get activity from (e.g., 'hyperliquid') */
+  provider: string
+  /** Wallet address */
+  address: Address
+  /** Maximum number of items to return */
+  limit?: number
+  /** Cursor for pagination */
+  cursor?: string
+  /** Filter: activity after this timestamp (ms) */
+  startTime?: number
+  /** Filter: activity before this timestamp (ms) */
+  endTime?: number
+  /** Filter by activity type(s) */
+  type?: ActivityType[]
+}
+
+/**
+ * Get account activity (deposits, withdrawals, liquidations, funding payments).
+ *
+ * @param client - The SDK client instance
+ * @param params - Request parameters
+ * @param options - Request options (e.g., AbortSignal)
+ * @returns Activity items with pagination
+ * @throws {PerpsError} On API error responses
+ * @throws {PerpsError} On network or parsing errors
+ *
+ * @example
+ * ```ts
+ * const client = createPerpsClient({ integrator: 'my-app' })
+ * const { items, pagination } = await getActivity(client, {
+ *   provider: 'hyperliquid',
+ *   address: '0x1234...',
+ *   limit: 50
+ * })
+ *
+ * // Fetch next page
+ * if (pagination.hasMore) {
+ *   const nextPage = await getActivity(client, {
+ *     provider: 'hyperliquid',
+ *     address: '0x1234...',
+ *     cursor: pagination.cursor
+ *   })
+ * }
+ * ```
+ */
+export async function getActivity(
+  client: PerpsSDKClient,
+  params: GetActivityParams,
+  options?: SDKRequestOptions
+): Promise<ActivitiesResponse> {
+  let url = buildUrl(`${client.config.apiUrl}/activity`, {
+    provider: params.provider,
+    address: params.address,
+    limit: params.limit,
+    cursor: params.cursor,
+    startTime: params.startTime,
+    endTime: params.endTime,
+  })
+  if (params.type?.length) {
+    const sep = url.includes('?') ? '&' : '?'
+    url +=
+      sep + params.type.map((t) => `type=${encodeURIComponent(t)}`).join('&')
+  }
+  return request<ActivitiesResponse>(client.config, url, {}, options)
+}

package/src/services/getAsset.ts

@@ -0,0 +1,34 @@
+import type { Asset } from '@lifi/perps-types'
+import type {
+  PerpsSDKClient,
+  SDKRequestOptions,
+} from '../client/createPerpsClient.js'
+import { buildUrl, request } from '../utils/request.js'
+
+export interface GetAssetParams {
+  /** Provider to get asset from (e.g., 'hyperliquid') */
+  provider: string
+  /** Asset symbol (e.g., 'BTC') */
+  symbol: string
+}
+
+/**
+ * Get a specific asset by symbol.
+ *
+ * @example
+ * ```ts
+ * const client = createPerpsClient({ integrator: 'my-app' })
+ * const asset = await getAsset(client, { provider: 'hyperliquid', symbol: 'BTC' })
+ * console.log(asset) // { symbol: 'BTC', markPrice: '95000.00', ... }
+ * ```
+ */
+export async function getAsset(
+  client: PerpsSDKClient,
+  params: GetAssetParams,
+  options?: SDKRequestOptions
+): Promise<Asset> {
+  const url = buildUrl(`${client.config.apiUrl}/assets/${params.symbol}`, {
+    provider: params.provider,
+  })
+  return request<Asset>(client.config, url, {}, options)
+}

package/src/services/getAssets.ts

@@ -0,0 +1,32 @@
+import type { AssetsResponse } from '@lifi/perps-types'
+import type {
+  PerpsSDKClient,
+  SDKRequestOptions,
+} from '../client/createPerpsClient.js'
+import { buildUrl, request } from '../utils/request.js'
+
+export interface GetAssetsParams {
+  /** Provider to get assets from (e.g., 'hyperliquid') */
+  provider: string
+}
+
+/**
+ * Get all available assets for a DEX, grouped by providerMarketId.
+ *
+ * @example
+ * ```ts
+ * const client = createPerpsClient({ integrator: 'my-app' })
+ * const { assets } = await getAssets(client, { provider: 'hyperliquid' })
+ * console.log(assets) // { hyperliquid: [...], xyz: [...], spot: [...] }
+ * ```
+ */
+export async function getAssets(
+  client: PerpsSDKClient,
+  params: GetAssetsParams,
+  options?: SDKRequestOptions
+): Promise<AssetsResponse> {
+  const url = buildUrl(`${client.config.apiUrl}/assets`, {
+    provider: params.provider,
+  })
+  return request<AssetsResponse>(client.config, url, {}, options)
+}