@lifi/perps-sdk 0.1.1-alpha.9 → 0.2.0-alpha.0

package/src/realtime/lighter/types.ts

@@ -0,0 +1,121 @@
+// ---------------------------------------------------------------------------
+// Lighter WebSocket message types
+//
+// The Lighter stream server sends JSON messages of shape:
+//   { type: 'subscribed/<channel>' | 'update/<channel>' | 'ping',
+//     channel: '<channel>/<id>',
+//     ...payload }
+//
+// Channels we subscribe to:
+//   - market_stats/all        → public prices across all markets
+//   - order_book/{market_id}  → bids/asks per market (stateful with deltas)
+// ---------------------------------------------------------------------------
+
+export type LtWsMessage = {
+  channel?: string
+  type: string
+}
+
+export type LtWsPingMessage = LtWsMessage & { type: 'ping' }
+
+export type LtWsMarketStats = {
+  market_id: number
+  index_price: string
+  mark_price: string
+  open_interest: string
+  last_trade_price: string
+  current_funding_rate: string
+  funding_rate: string
+  funding_timestamp: number
+  daily_base_token_volume: string
+  daily_quote_token_volume: string
+  daily_price_change: string
+}
+
+/**
+ * `market_stats/all` pushes one record per known market each tick. We
+ * aggregate them into a Record<assetId, price> before emitting `prices`.
+ */
+export type LtWsMarketStatsAllMessage = LtWsMessage & {
+  type: 'subscribed/market_stats' | 'update/market_stats'
+  market_stats?: Record<string, LtWsMarketStats>
+}
+
+export type LtWsOrderBookLevel = {
+  price: string
+  size: string
+}
+
+export type LtWsOrderBook = {
+  asks: LtWsOrderBookLevel[]
+  bids: LtWsOrderBookLevel[]
+  offset?: number
+}
+
+export type LtWsOrderBookMessage = LtWsMessage & {
+  type: 'subscribed/order_book' | 'update/order_book'
+  order_book: LtWsOrderBook
+}
+
+export type LtOrderBookDetail = {
+  symbol: string
+  market_id: number
+  market_type: string
+  supported_price_decimals: number
+  supported_size_decimals: number
+}
+
+export type LtOrderBookDetailsResponse = {
+  code: number
+  order_book_details: LtOrderBookDetail[]
+}
+
+/**
+ * `/api/v1/account?by=l1_address` response. The provider only consumes the
+ * `index` field — everything else is intentionally typed as unknown.
+ */
+export type LtWsAccountByL1Response = {
+  code: number
+  accounts?: Array<{ index: number; [k: string]: unknown }>
+}
+
+/**
+ * Auth-channel payloads.
+ *
+ * The response `channel` field uses `:` as separator (e.g.
+ * `account_all_orders:42`) while the subscribe payload uses `/`.
+ *
+ * Per the Lighter WS spec:
+ *   - orders/trades: object indexed by market index, each value an array
+ *     (`{ "0": [Order], "1": [Order] }`)
+ *   - positions: object indexed by market index, each value a single object
+ *     (`{ "0": Position }`)
+ *   - initial `account_all_trades` snapshot may send an empty flat array
+ *
+ * The provider uses `collectAuthChannelItems` to normalise all three shapes
+ * into a flat T[].
+ */
+export type LtWsAccountAllOrdersMessage = LtWsMessage & {
+  type: 'subscribed/account_all_orders' | 'update/account_all_orders'
+  orders?: Record<string, unknown[]> | unknown[]
+  data?: { orders?: Record<string, unknown[]> | unknown[] }
+}
+
+export type LtWsAccountAllTradesMessage = LtWsMessage & {
+  type: 'subscribed/account_all_trades' | 'update/account_all_trades'
+  trades?: Record<string, unknown[]> | unknown[]
+  total_volume?: number
+  monthly_volume?: number
+  weekly_volume?: number
+  daily_volume?: number
+  data?: { trades?: Record<string, unknown[]> | unknown[] }
+}
+
+export type LtWsAccountAllPositionsMessage = LtWsMessage & {
+  type: 'subscribed/account_all_positions' | 'update/account_all_positions'
+  positions?: Record<string, unknown>
+  shares?: unknown[]
+  last_funding_round?: Record<string, string>
+  last_funding_discount?: Record<string, string>
+  data?: { positions?: Record<string, unknown> }
+}

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,37 @@
+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/${encodeURIComponent(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)
+}

package/src/services/{getHistory.ts → getFills.ts}

@@ -1,36 +1,40 @@
-import type { Address, HistoryResponse } from '@lifi/perps-types'
+import type { Address, FillsResponse } from '@lifi/perps-types'
 import type {
   PerpsSDKClient,
   SDKRequestOptions,
 } from '../client/createPerpsClient.js'
 import { buildUrl, request } from '../utils/request.js'
 
-export interface GetHistoryParams {
-  /** DEX to get history from (e.g., 'hyperliquid') */
-  dex: string
+export interface GetFillsParams {
+  /** Provider to get fills from (e.g., 'hyperliquid') */
+  provider: string
   /** Wallet address */
   address: Address
   /** Maximum number of items to return */
   limit?: number
   /** Cursor for pagination */
   cursor?: string
+  /** Filter: orders after this timestamp (ms) */
+  startTime?: number
+  /** Filter: orders before this timestamp (ms) */
+  endTime?: number
 }
 
 /**
- * Get order history for an account.
+ * Get order fills for an account.
  *
  * @param client - The SDK client instance
  * @param params - Request parameters
  * @param options - Request options (e.g., AbortSignal)
- * @returns Order history with pagination
- * @throws {HTTPError} On API error responses
+ * @returns Order fills 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 getHistory(client, {
- *   dex: 'hyperliquid',
+ * const { items, pagination } = await getFills(client, {
+ *   provider: 'hyperliquid',
  *   address: '0x1234...',
  *   limit: 50
  * })
@@ -39,24 +43,26 @@ export interface GetHistoryParams {
  *
  * // Fetch next page
  * if (pagination.hasMore) {
- *   const nextPage = await getHistory(client, {
- *     dex: 'hyperliquid',
+ *   const nextPage = await getFills(client, {
+ *     provider: 'hyperliquid',
  *     address: '0x1234...',
  *     cursor: pagination.cursor
  *   })
  * }
  * ```
  */
-export async function getHistory(
+export async function getFills(
   client: PerpsSDKClient,
-  params: GetHistoryParams,
+  params: GetFillsParams,
   options?: SDKRequestOptions
-): Promise<HistoryResponse> {
-  const url = buildUrl(`${client.config.apiUrl}/history`, {
-    dex: params.dex,
+): Promise<FillsResponse> {
+  const url = buildUrl(`${client.config.apiUrl}/fills`, {
+    provider: params.provider,
     address: params.address,
     limit: params.limit,
     cursor: params.cursor,
+    startTime: params.startTime,
+    endTime: params.endTime,
   })
-  return request<HistoryResponse>(client.config, url, {}, options)
+  return request<FillsResponse>(client.config, url, {}, options)
 }

package/src/services/getOhlcv.ts

@@ -6,8 +6,8 @@ import type {
 import { buildUrl, request } from '../utils/request.js'
 
 export interface GetOhlcvParams {
-  /** DEX to get OHLCV from (e.g., 'hyperliquid') */
-  dex: string
+  /** Provider to get OHLCV from (e.g., 'hyperliquid') */
+  provider: string
   /** Market symbol (e.g., 'BTC') */
   symbol: string
   /** Candle interval */
@@ -27,14 +27,14 @@ export interface GetOhlcvParams {
  * @param params - Request parameters
  * @param options - Request options (e.g., AbortSignal)
  * @returns OHLCV candle data
- * @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 { candles } = await getOhlcv(client, {
- *   dex: 'hyperliquid',
+ *   provider: 'hyperliquid',
  *   symbol: 'BTC',
  *   interval: '1h',
  *   limit: 100
@@ -47,12 +47,15 @@ export async function getOhlcv(
   params: GetOhlcvParams,
   options?: SDKRequestOptions
 ): Promise<OhlcvResponse> {
-  const url = buildUrl(`${client.config.apiUrl}/ohlcv/${params.symbol}`, {
-    dex: params.dex,
-    interval: params.interval,
-    startTime: params.startTime,
-    endTime: params.endTime,
-    limit: params.limit,
-  })
+  const url = buildUrl(
+    `${client.config.apiUrl}/ohlcv/${encodeURIComponent(params.symbol)}`,
+    {
+      provider: params.provider,
+      interval: params.interval,
+      startTime: params.startTime,
+      endTime: params.endTime,
+      limit: params.limit,
+    }
+  )
   return request<OhlcvResponse>(client.config, url, {}, options)
 }

package/src/services/getOrder.ts

@@ -6,8 +6,8 @@ import type {
 import { buildUrl, request } from '../utils/request.js'
 
 export interface GetOrderParams {
-  /** DEX to get order from (e.g., 'hyperliquid') */
-  dex: string
+  /** Provider to get order from (e.g., 'hyperliquid') */
+  provider: string
   /** Wallet address */
   address: Address
   /** Order ID */
@@ -21,14 +21,14 @@ export interface GetOrderParams {
  * @param params - Request parameters
  * @param options - Request options (e.g., AbortSignal)
  * @returns Order details
- * @throws {HTTPError} On API error responses (e.g., 404 if order not found)
+ * @throws {PerpsError} On API error responses (e.g., 404 if order not found)
  * @throws {PerpsError} On network or parsing errors
  *
  * @example
  * ```ts
  * const client = createPerpsClient({ integrator: 'my-app' })
  * const order = await getOrder(client, {
- *   dex: 'hyperliquid',
+ *   provider: 'hyperliquid',
  *   address: '0x1234...',
  *   id: '123456'
  * })
@@ -40,9 +40,12 @@ export async function getOrder(
   params: GetOrderParams,
   options?: SDKRequestOptions
 ): Promise<Order> {
-  const url = buildUrl(`${client.config.apiUrl}/order/${params.id}`, {
-    dex: params.dex,
-    address: params.address,
-  })
+  const url = buildUrl(
+    `${client.config.apiUrl}/order/${encodeURIComponent(params.id)}`,
+    {
+      provider: params.provider,
+      address: params.address,
+    }
+  )
   return request<Order>(client.config, url, {}, options)
 }

package/src/services/getOrderbook.ts

@@ -6,8 +6,8 @@ import type {
 import { buildUrl, request } from '../utils/request.js'
 
 export interface GetOrderbookParams {
-  /** DEX to get orderbook from (e.g., 'hyperliquid') */
-  dex: string
+  /** Provider to get orderbook from (e.g., 'hyperliquid') */
+  provider: string
   /** Market symbol (e.g., 'BTC') */
   symbol: string
   /** Number of levels to return (default varies by DEX) */
@@ -21,14 +21,14 @@ export interface GetOrderbookParams {
  * @param params - Request parameters
  * @param options - Request options (e.g., AbortSignal)
  * @returns Orderbook with bids and asks
- * @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 { bids, asks } = await getOrderbook(client, {
- *   dex: 'hyperliquid',
+ *   provider: 'hyperliquid',
  *   symbol: 'BTC',
  *   depth: 20
  * })
@@ -41,9 +41,12 @@ export async function getOrderbook(
   params: GetOrderbookParams,
   options?: SDKRequestOptions
 ): Promise<OrderbookResponse> {
-  const url = buildUrl(`${client.config.apiUrl}/orderbook/${params.symbol}`, {
-    dex: params.dex,
-    depth: params.depth,
-  })
+  const url = buildUrl(
+    `${client.config.apiUrl}/orderbook/${encodeURIComponent(params.symbol)}`,
+    {
+      provider: params.provider,
+      depth: params.depth,
+    }
+  )
   return request<OrderbookResponse>(client.config, url, {}, options)
 }

package/src/services/getOrders.ts

@@ -0,0 +1,45 @@
+import type { Address, OrdersResponse } from '@lifi/perps-types'
+import type {
+  PerpsSDKClient,
+  SDKRequestOptions,
+} from '../client/createPerpsClient.js'
+import { buildUrl, request } from '../utils/request.js'
+
+export interface GetOrdersParams {
+  /** Provider (e.g., 'hyperliquid') */
+  provider: string
+  /** Wallet address */
+  address: Address
+  /** Optional symbol to filter orders by market */
+  symbol?: string
+  /** Maximum number of results */
+  limit?: number
+  /** Pagination cursor */
+  cursor?: string
+}
+
+/**
+ * Get open orders and trigger orders for an account.
+ *
+ * @example
+ * ```ts
+ * const { openOrders, triggerOrders } = await getOrders(client, {
+ *   provider: 'hyperliquid',
+ *   address: '0x1234...',
+ * })
+ * ```
+ */
+export async function getOrders(
+  client: PerpsSDKClient,
+  params: GetOrdersParams,
+  options?: SDKRequestOptions
+): Promise<OrdersResponse> {
+  const url = buildUrl(`${client.config.apiUrl}/orders`, {
+    provider: params.provider,
+    address: params.address,
+    ...(params.symbol ? { symbol: params.symbol } : {}),
+    ...(params.limit ? { limit: String(params.limit) } : {}),
+    ...(params.cursor ? { cursor: params.cursor } : {}),
+  })
+  return request<OrdersResponse>(client.config, url, {}, options)
+}