@lifi/perps-sdk 0.1.1-alpha.9 → 1.0.0

package/src/realtime/hyperliquid/HyperliquidWsProvider.ts

@@ -1,278 +0,0 @@
-import type { Subscription, SubscriptionEvent } from '@lifi/perps-types'
-import { HistoryItemStatus, OrderSide, OrderType } from '@lifi/perps-types'
-import type {
-  HlAssetPosition,
-  HlOrderDetail,
-  HlUserFill,
-} from '@lifi/perps-types/providers/hyperliquid'
-import {
-  mapHistoryItem,
-  mapOrder,
-  mapPosition,
-} from '@lifi/perps-types/providers/hyperliquid'
-import { ReconnectingWebSocket } from '../ReconnectingWebSocket.js'
-import type { SubscriptionListener, WsProvider } from '../types.js'
-import type {
-  HlWsAllMidsData,
-  HlWsCandleData,
-  HlWsL2BookData,
-  HlWsMessage,
-  HlWsTrade,
-  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
-    this.rws = new ReconnectingWebSocket(wsUrl)
-    this.rws.on('message', (data) => this.handleMessage(data))
-    this.rws.on('open', () => this.resubscribeAll())
-  }
-
-  async subscribe(
-    sub: Subscription,
-    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)
-
-    const existing = this.subs.get(key)
-    if (existing) {
-      existing.count++
-    } else {
-      this.subs.set(key, { count: 1, payload })
-      await this.rws.ready()
-      this.rws.send(
-        JSON.stringify({ method: 'subscribe', subscription: payload })
-      )
-    }
-
-    return () => {
-      this.listeners.get(key)?.delete(listener)
-      const s = this.subs.get(key)
-      if (s) {
-        s.count--
-        if (s.count <= 0) {
-          this.subs.delete(key)
-          this.listeners.delete(key)
-          this.rws.send(
-            JSON.stringify({ method: 'unsubscribe', subscription: payload })
-          )
-        }
-      }
-    }
-  }
-
-  close() {
-    this.rws.close()
-    this.subs.clear()
-    this.listeners.clear()
-  }
-
-  private resubscribeAll() {
-    for (const { payload } of this.subs.values()) {
-      this.rws.send(
-        JSON.stringify({ method: 'subscribe', subscription: payload })
-      )
-    }
-  }
-
-  private toKey(sub: Subscription): string {
-    switch (sub.channel) {
-      case 'prices':
-        return 'allMids'
-      case 'orderbook':
-        return `l2Book:${sub.symbol}`
-      case 'trades':
-        return `trades:${sub.symbol}`
-      case 'candle':
-        return `candle:${sub.symbol}:${sub.interval}`
-      case 'orderUpdates':
-        return `orderUpdates:${sub.address}`
-      case 'fills':
-        return `userFills:${sub.address}`
-      case 'positions':
-        return `webData2:${sub.address}`
-    }
-  }
-
-  private toHlPayload(sub: Subscription): object {
-    switch (sub.channel) {
-      case 'prices':
-        return { type: 'allMids' }
-      case 'orderbook':
-        return {
-          type: 'l2Book',
-          coin: sub.symbol,
-          ...(sub.depth !== undefined ? { nLevels: sub.depth } : {}),
-        }
-      case 'trades':
-        return { type: 'trades', coin: sub.symbol }
-      case 'candle':
-        return { type: 'candle', coin: sub.symbol, 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 }
-    }
-  }
-
-  private emit(key: string, event: SubscriptionEvent) {
-    const fns = this.listeners.get(key)
-    if (fns) {
-      for (const fn of fns) {
-        fn(event)
-      }
-    }
-  }
-
-  private emitToPrefix(prefix: string, event: SubscriptionEvent) {
-    for (const [key, fns] of this.listeners) {
-      if (key.startsWith(prefix)) {
-        for (const fn of fns) {
-          fn(event)
-        }
-      }
-    }
-  }
-
-  private handleMessage(raw: string) {
-    let msg: HlWsMessage
-    try {
-      msg = JSON.parse(raw)
-    } catch {
-      return
-    }
-    if (
-      !msg.channel ||
-      msg.channel === 'pong' ||
-      msg.channel === 'subscriptionResponse'
-    ) {
-      return
-    }
-
-    try {
-      switch (msg.channel) {
-        case 'allMids':
-          this.handleAllMids(msg.data as HlWsAllMidsData)
-          break
-        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
-        case 'orderUpdates':
-          this.handleOrderUpdates(msg.data as HlOrderDetail[])
-          break
-        case 'userFills':
-          this.handleUserFills(msg.data as HlWsUserFillsData)
-          break
-        case 'webData2':
-          this.handleWebData2(msg.data as HlWsWebData2Data)
-          break
-      }
-    } catch {
-      // Skip malformed messages
-    }
-  }
-
-  private handleAllMids(data: HlWsAllMidsData) {
-    this.emit('allMids', { channel: 'prices', data: { prices: data.mids } })
-  }
-
-  private handleL2Book(data: HlWsL2BookData) {
-    this.emit(`l2Book:${data.coin}`, {
-      channel: 'orderbook',
-      data: {
-        dex: this.dexKey,
-        symbol: 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,
-      },
-    })
-  }
-
-  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',
-      data: {
-        t: data.t,
-        o: data.o,
-        h: data.h,
-        l: data.l,
-        c: data.c,
-        v: data.v,
-      },
-    })
-  }
-
-  private handleOrderUpdates(data: HlOrderDetail[]) {
-    const orders = data.map((d) => mapOrder(d))
-    this.emitToPrefix('orderUpdates:', {
-      channel: 'orderUpdates',
-      data: orders,
-    })
-  }
-
-  private handleUserFills(data: HlWsUserFillsData) {
-    const items = data.fills.map((f) =>
-      mapHistoryItem(f as HlUserFill, this.dexKey, this.assetIdLookup)
-    )
-    this.emit(`userFills:${data.user}`, { channel: 'fills', data: items })
-  }
-
-  private handleWebData2(data: HlWsWebData2Data) {
-    const positions = data.clearinghouseState.assetPositions.map((ap) =>
-      mapPosition(ap as HlAssetPosition, this.dexKey, this.assetIdLookup)
-    )
-    this.emit(`webData2:${data.user}`, {
-      channel: 'positions',
-      data: positions,
-    })
-  }
-}

package/src/realtime/hyperliquid/types.ts

@@ -1,48 +0,0 @@
-// Hyperliquid WebSocket incoming message types
-// Derived from @lifi/perps-types where possible to avoid duplication.
-
-import type {
-  HlAllMids,
-  HlCandle,
-  HlClearinghouseState,
-  HlL2Book,
-  HlUserFill,
-} from '@lifi/perps-types/providers/hyperliquid'
-
-export type HlWsMessage = {
-  channel: string
-  data: unknown
-}
-
-export type HlWsAllMidsData = {
-  mids: HlAllMids
-}
-
-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
-  i: string
-  n: number
-}
-
-export type HlWsUserFillsData = {
-  isSnapshot: boolean
-  user: string
-  fills: HlUserFill[]
-}
-
-export type HlWsWebData2Data = {
-  user: string
-  clearinghouseState: Pick<HlClearinghouseState, 'assetPositions'>
-}

package/src/realtime/types.ts

@@ -1,16 +0,0 @@
-import type { Subscription, SubscriptionEvent } from '@lifi/perps-types'
-
-export type EventForSubscription<S extends Subscription> = Extract<
-  SubscriptionEvent,
-  { channel: S['channel'] }
->
-
-export type SubscriptionListener = (event: SubscriptionEvent) => void
-
-export interface WsProvider {
-  subscribe(
-    sub: Subscription,
-    listener: SubscriptionListener
-  ): Promise<() => void>
-  close(): void
-}

package/src/services/cancelOrder.ts

@@ -1,75 +0,0 @@
-import type { Address, CancelOrderPayloadResponse } from '@lifi/perps-types'
-import type {
-  PerpsSDKClient,
-  SDKRequestOptions,
-} from '../client/createPerpsClient.js'
-import { request } from '../utils/request.js'
-
-export interface CancelOrderParams {
-  /** DEX to cancel orders on (e.g., 'hyperliquid') */
-  dex: string
-  /** Wallet address */
-  address: Address
-  /** Address of the signer (for agent mode, this is the agent address) */
-  signerAddress?: Address
-  /** Order IDs to cancel */
-  ids: string[]
-}
-
-/**
- * Create cancel order payloads for signing.
- * Returns typed data that must be signed by the user or agent.
- *
- * @param client - The SDK client instance
- * @param params - Request parameters
- * @param options - Request options (e.g., AbortSignal)
- * @returns Cancel actions with typed data for signing
- * @throws {HTTPError} On API error responses
- * @throws {PerpsError} On network or parsing errors
- *
- * @example
- * ```ts
- * const client = createPerpsClient({ integrator: 'my-app' })
- * const { actions } = await cancelOrder(client, {
- *   dex: 'hyperliquid',
- *   address: '0x1234...',
- *   ids: ['order1', 'order2']
- * })
- *
- * // Sign with agent key or user wallet
- * const signedActions = await Promise.all(
- *   actions.map(async (a) => ({
- *     action: a.action,
- *     typedData: a.typedData,
- *     signature: await signTypedData(agentPrivateKey, a.typedData)
- *   }))
- * )
- *
- * // Submit the signed cancellation
- * await submitOrder(client, {
- *   dex: 'hyperliquid',
- *   address: '0x1234...',
- *   actions: signedActions
- * })
- * ```
- */
-export async function cancelOrder(
-  client: PerpsSDKClient,
-  params: CancelOrderParams,
-  options?: SDKRequestOptions
-): Promise<CancelOrderPayloadResponse> {
-  return request<CancelOrderPayloadResponse>(
-    client.config,
-    `${client.config.apiUrl}/cancelOrder`,
-    {
-      method: 'POST',
-      body: JSON.stringify({
-        dex: params.dex,
-        address: params.address,
-        signerAddress: params.signerAddress,
-        ids: params.ids,
-      }),
-    },
-    options
-  )
-}

package/src/services/createAuthorization.ts

@@ -1,79 +0,0 @@
-import type {
-  Address,
-  AuthorizationInput,
-  CreateAuthorizationResponse,
-} from '@lifi/perps-types'
-import type {
-  PerpsSDKClient,
-  SDKRequestOptions,
-} from '../client/createPerpsClient.js'
-import { request } from '../utils/request.js'
-
-export interface CreateAuthorizationParams {
-  /** DEX to authorize (e.g., 'hyperliquid') */
-  dex: string
-  /** Wallet address */
-  address: Address
-  /** Address of the signer (for agent mode, this is the agent address) */
-  signerAddress?: Address
-  /** List of authorizations to create */
-  authorizations: AuthorizationInput[]
-}
-
-/**
- * Create authorization payloads for signing.
- * Returns typed data that must be signed by the user or agent.
- *
- * @param client - The SDK client instance
- * @param params - Request parameters
- * @param options - Request options (e.g., AbortSignal)
- * @returns Authorization actions with typed data for signing
- * @throws {HTTPError} On API error responses
- * @throws {PerpsError} On network or parsing errors
- *
- * @remarks
- * The example below uses Hyperliquid authorization keys. Use `getDexes()` to discover
- * available authorizations for each DEX.
- *
- * @example
- * ```ts
- * const client = createPerpsClient({ integrator: 'my-app' })
- * const { actions } = await createAuthorization(client, {
- *   dex: 'hyperliquid',
- *   address: '0x1234...',
- *   authorizations: [
- *     { key: 'ApproveAgent', params: { agentAddress: '0xabcd...' } },
- *     { key: 'ApproveBuilderFee' }
- *   ]
- * })
- *
- * // Sign each action's typedData with the user's wallet
- * const signedActions = await Promise.all(
- *   actions.map(async (a) => ({
- *     action: a.action,
- *     typedData: a.typedData,
- *     signature: await walletClient.signTypedData(a.typedData)
- *   }))
- * )
- * ```
- */
-export async function createAuthorization(
-  client: PerpsSDKClient,
-  params: CreateAuthorizationParams,
-  options?: SDKRequestOptions
-): Promise<CreateAuthorizationResponse> {
-  return request<CreateAuthorizationResponse>(
-    client.config,
-    `${client.config.apiUrl}/createAuthorization`,
-    {
-      method: 'POST',
-      body: JSON.stringify({
-        dex: params.dex,
-        address: params.address,
-        signerAddress: params.signerAddress,
-        authorizations: params.authorizations,
-      }),
-    },
-    options
-  )
-}

package/src/services/createOrder.ts

@@ -1,116 +0,0 @@
-import type {
-  Address,
-  CreateOrderResponse,
-  OrderSide,
-  OrderType,
-  TimeInForce,
-  TriggerOrderInput,
-} from '@lifi/perps-types'
-import type {
-  PerpsSDKClient,
-  SDKRequestOptions,
-} from '../client/createPerpsClient.js'
-import { request } from '../utils/request.js'
-
-export interface CreateOrderParams {
-  /** DEX to place order on (e.g., 'hyperliquid') */
-  dex: string
-  /** Wallet address */
-  address: Address
-  /** Address of the signer (for agent mode, this is the agent address) */
-  signerAddress?: Address
-  /** Client-provided order ID for tracking */
-  clientOrderId?: string
-  /** Market symbol (e.g., 'BTC') */
-  symbol: string
-  /** Order side */
-  side: OrderSide
-  /** Order type */
-  type: OrderType
-  /** Order size (in base asset) */
-  size: string
-  /** Order price (required for limit orders) */
-  price: string
-  /** Leverage for the position */
-  leverage?: number
-  /** Whether this order only reduces position */
-  reduceOnly?: boolean
-  /** Time in force */
-  timeInForce?: TimeInForce
-  /** Expiration time (ISO 8601) */
-  expiresAt?: string
-  /** Take profit trigger order */
-  takeProfit?: TriggerOrderInput
-  /** Stop loss trigger order */
-  stopLoss?: TriggerOrderInput
-}
-
-/**
- * Create order payloads for signing.
- * Returns typed data that must be signed by the user or agent.
- *
- * @param client - The SDK client instance
- * @param params - Request parameters
- * @param options - Request options (e.g., AbortSignal)
- * @returns Order actions with typed data for signing
- * @throws {HTTPError} On API error responses
- * @throws {PerpsError} On network or parsing errors
- *
- * @remarks
- * The example below uses Hyperliquid. Replace the `dex` value for other DEXes.
- *
- * @example
- * ```ts
- * const client = createPerpsClient({ integrator: 'my-app' })
- * const { actions } = await createOrder(client, {
- *   dex: 'hyperliquid',
- *   address: '0x1234...',
- *   symbol: 'BTC',
- *   side: OrderSide.BUY,
- *   type: OrderType.LIMIT,
- *   size: '0.1',
- *   price: '94000.00',
- *   leverage: 10
- * })
- *
- * // Sign each action with the user's wallet or agent key
- * const signedActions = await Promise.all(
- *   actions.map(async (a) => ({
- *     action: a.action,
- *     typedData: a.typedData,
- *     signature: await walletClient.signTypedData(a.typedData)
- *   }))
- * )
- * ```
- */
-export async function createOrder(
-  client: PerpsSDKClient,
-  params: CreateOrderParams,
-  options?: SDKRequestOptions
-): Promise<CreateOrderResponse> {
-  return request<CreateOrderResponse>(
-    client.config,
-    `${client.config.apiUrl}/createOrder`,
-    {
-      method: 'POST',
-      body: JSON.stringify({
-        dex: params.dex,
-        address: params.address,
-        signerAddress: params.signerAddress,
-        clientOrderId: params.clientOrderId,
-        symbol: params.symbol,
-        side: params.side,
-        type: params.type,
-        size: params.size,
-        price: params.price,
-        leverage: params.leverage,
-        reduceOnly: params.reduceOnly,
-        timeInForce: params.timeInForce,
-        expiresAt: params.expiresAt,
-        takeProfit: params.takeProfit,
-        stopLoss: params.stopLoss,
-      }),
-    },
-    options
-  )
-}

package/src/services/createWithdrawal.ts

@@ -1,76 +0,0 @@
-import type {
-  Address,
-  CreateWithdrawalResponse,
-  WithdrawalInput,
-} from '@lifi/perps-types'
-import type {
-  PerpsSDKClient,
-  SDKRequestOptions,
-} from '../client/createPerpsClient.js'
-import { request } from '../utils/request.js'
-
-export interface CreateWithdrawalParams {
-  /** DEX to withdraw from (e.g., 'hyperliquid') */
-  dex: string
-  /** Wallet address (account owner) */
-  address: Address
-  /** Withdrawal details (destination address and amount) */
-  withdrawal: WithdrawalInput
-}
-
-/**
- * Create a withdrawal payload for signing.
- * Returns typed data that must be signed by the user's wallet.
- *
- * Withdrawals are user-signed only — agents cannot initiate withdrawals.
- * This is a protocol-level security feature.
- *
- * @param client - The SDK client instance
- * @param params - Request parameters
- * @param options - Request options (e.g., AbortSignal)
- * @returns Withdrawal action with typed data for signing
- * @throws {HTTPError} On API error responses
- * @throws {PerpsError} On network or parsing errors
- *
- * @remarks
- * The example below uses Hyperliquid. Withdrawal mechanics vary by DEX.
- *
- * @example
- * ```ts
- * const client = createPerpsClient({ integrator: 'my-app' })
- * const { action } = await createWithdrawal(client, {
- *   dex: 'hyperliquid',
- *   address: '0x1234...',
- *   withdrawal: {
- *     destination: '0x1234...',
- *     amount: '100.0',
- *   },
- * })
- *
- * // Sign the action's typedData with the user's wallet
- * const signedAction = {
- *   action: action.action,
- *   typedData: action.typedData,
- *   signature: await walletClient.signTypedData(action.typedData),
- * }
- * ```
- */
-export async function createWithdrawal(
-  client: PerpsSDKClient,
-  params: CreateWithdrawalParams,
-  options?: SDKRequestOptions
-): Promise<CreateWithdrawalResponse> {
-  return request<CreateWithdrawalResponse>(
-    client.config,
-    `${client.config.apiUrl}/createWithdrawal`,
-    {
-      method: 'POST',
-      body: JSON.stringify({
-        dex: params.dex,
-        address: params.address,
-        withdrawal: params.withdrawal,
-      }),
-    },
-    options
-  )
-}