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

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
@@ -48,7 +48,7 @@ export async function getOhlcv(
   options?: SDKRequestOptions
 ): Promise<OhlcvResponse> {
   const url = buildUrl(`${client.config.apiUrl}/ohlcv/${params.symbol}`, {
-    dex: params.dex,
+    provider: params.provider,
     interval: params.interval,
     startTime: params.startTime,
     endTime: params.endTime,

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'
  * })
@@ -41,7 +41,7 @@ export async function getOrder(
   options?: SDKRequestOptions
 ): Promise<Order> {
   const url = buildUrl(`${client.config.apiUrl}/order/${params.id}`, {
-    dex: params.dex,
+    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
  * })
@@ -42,7 +42,7 @@ export async function getOrderbook(
   options?: SDKRequestOptions
 ): Promise<OrderbookResponse> {
   const url = buildUrl(`${client.config.apiUrl}/orderbook/${params.symbol}`, {
-    dex: params.dex,
+    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)
+}

package/src/services/getPositions.ts

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

package/src/services/getPrices.ts

@@ -6,8 +6,8 @@ import type {
 import { buildUrl, request } from '../utils/request.js'
 
 export interface GetPricesParams {
-  /** DEX to get prices from (e.g., 'hyperliquid') */
-  dex: string
+  /** Provider to get prices from (e.g., 'hyperliquid') */
+  provider: string
   /** Optional list of symbols to filter (e.g., ['BTC', 'ETH']) */
   symbols?: string[]
 }
@@ -19,18 +19,18 @@ export interface GetPricesParams {
  * @param params - Request parameters
  * @param options - Request options (e.g., AbortSignal)
  * @returns Map of symbol to price
- * @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 { prices } = await getPrices(client, { dex: 'hyperliquid' })
+ * const { prices } = await getPrices(client, { provider: 'hyperliquid' })
  * console.log(prices) // { BTC: '95000.00', ETH: '3400.00', ... }
  *
  * // Filter by symbols
  * const { prices } = await getPrices(client, {
- *   dex: 'hyperliquid',
+ *   provider: 'hyperliquid',
  *   symbols: ['BTC', 'ETH']
  * })
  * ```
@@ -41,7 +41,7 @@ export async function getPrices(
   options?: SDKRequestOptions
 ): Promise<PricesResponse> {
   const url = buildUrl(`${client.config.apiUrl}/prices`, {
-    dex: params.dex,
+    provider: params.provider,
     symbols: params.symbols?.join(','),
   })
   return request<PricesResponse>(client.config, url, {}, options)

package/src/services/{getDexes.ts → getProviders.ts}

@@ -1,4 +1,4 @@
-import type { DexesResponse } from '@lifi/perps-types'
+import type { ProvidersResponse } from '@lifi/perps-types'
 import type {
   PerpsSDKClient,
   SDKRequestOptions,
@@ -6,28 +6,28 @@ import type {
 import { request } from '../utils/request.js'
 
 /**
- * Get all available DEXes.
+ * Get all available providers.
  *
  * @param client - The SDK client instance
  * @param options - Request options (e.g., AbortSignal)
- * @returns List of supported DEXes with their authorization requirements
- * @throws {HTTPError} On API error responses
+ * @returns List of supported providers with their authorization requirements
+ * @throws {PerpsError} On API error responses
  * @throws {PerpsError} On network or parsing errors
  *
  * @example
  * ```ts
  * const client = createPerpsClient({ integrator: 'my-app' })
- * const { dexes } = await getDexes(client)
- * console.log(dexes) // [{ key: 'hyperliquid', name: 'Hyperliquid', ... }]
+ * const { providers } = await getProviders(client)
+ * console.log(providers) // [{ key: 'hyperliquid', name: 'Hyperliquid', ... }]
  * ```
  */
-export async function getDexes(
+export async function getProviders(
   client: PerpsSDKClient,
   options?: SDKRequestOptions
-): Promise<DexesResponse> {
-  return request<DexesResponse>(
+): Promise<ProvidersResponse> {
+  return request<ProvidersResponse>(
     client.config,
-    `${client.config.apiUrl}/dexes`,
+    `${client.config.apiUrl}/providers`,
     {},
     options
   )

package/src/utils/accountSummary.ts

@@ -0,0 +1,124 @@
+import type { AccountResponse, Asset, Position } from '@lifi/perps-types'
+import { HlAbstractionMode } from '@lifi/perps-types/providers/hyperliquid'
+import { stringToFloat } from './parse.js'
+
+export interface AccountSummary {
+  /** Total portfolio value in USD */
+  portfolioValue: number
+  /** Collateral available for new positions */
+  availableMargin: number
+  /** Margin locked in open positions */
+  marginUsed: number
+  /** Unrealized PnL across all positions */
+  unrealizedPnl: number
+}
+
+/**
+ * Build a map of coin name → USD price from spot assets and allMids.
+ * Spot assets have displaySymbol "BASE/QUOTE" and assetId "@N" which keys into prices.
+ */
+function buildSpotCoinPrices(
+  assets: Asset[],
+  prices: Record<string, string>
+): Map<string, number> {
+  const map = new Map<string, number>()
+  for (const asset of assets) {
+    if (asset.market !== 'spot') {
+      continue
+    }
+    const price = prices[asset.assetId]
+    if (!price) {
+      continue
+    }
+    const slashIdx = asset.displaySymbol.indexOf('/')
+    if (slashIdx < 0) {
+      continue
+    }
+    const base = asset.displaySymbol.slice(0, slashIdx)
+    map.set(base, stringToFloat(price))
+  }
+  return map
+}
+
+/**
+ * Resolve the USD price of a spot balance currency.
+ *
+ * Looks up the coin in the spot mid prices map first, then tries an exact
+ * match in allMids (e.g. a perps-listed stablecoin). Falls back to $1 for
+ * stablecoins with no market price entry.
+ */
+function getSpotPrice(
+  currency: string,
+  prices: Record<string, string>,
+  spotCoinPrices: Map<string, number>
+): number {
+  const spotPrice = spotCoinPrices.get(currency)
+  if (spotPrice !== undefined) {
+    return spotPrice
+  }
+  if (prices[currency] !== undefined) {
+    return stringToFloat(prices[currency])
+  }
+  return 1
+}
+
+const UNIFIED_STATUSES: ReadonlySet<string> = new Set([
+  HlAbstractionMode.UNIFIED_ACCOUNT,
+  HlAbstractionMode.PORTFOLIO_MARGIN,
+])
+
+export function calculateAccountSummary(
+  account: AccountResponse,
+  positions: Position[],
+  prices: Record<string, string>,
+  assets?: Asset[],
+  collateralCurrencies?: ReadonlySet<string>
+): AccountSummary {
+  let marginUsed = 0
+  let unrealizedPnl = 0
+  for (const p of positions) {
+    marginUsed += stringToFloat(p.marginUsed)
+    unrealizedPnl += stringToFloat(p.unrealizedPnl)
+  }
+
+  const spotCoinPrices = buildSpotCoinPrices(assets ?? [], prices)
+
+  // Split spot into margin-eligible (quote assets) and non-margin (HYPE, PURR etc.)
+  let spotMarginValue = 0
+  let spotNonMarginValue = 0
+  let perpsBalance = 0
+  for (const [key, entries] of Object.entries(account.balances)) {
+    if (key === 'spot') {
+      for (const b of entries) {
+        const value =
+          stringToFloat(b.amount) *
+          getSpotPrice(b.currency, prices, spotCoinPrices)
+        if (!collateralCurrencies || collateralCurrencies.has(b.currency)) {
+          spotMarginValue += value
+        } else {
+          spotNonMarginValue += value
+        }
+      }
+    } else {
+      for (const b of entries) {
+        perpsBalance += stringToFloat(b.amount)
+      }
+    }
+  }
+
+  const status = account.config?.abstractionStatus as string | undefined
+  const isUnified = UNIFIED_STATUSES.has(status ?? '')
+
+  // Unified: spot balances are total token holdings (margin is NOT subtracted).
+  // Disabled: perps venue balances are free margin (margin IS already subtracted).
+  const marginCollateral = isUnified
+    ? spotMarginValue + perpsBalance
+    : spotMarginValue + perpsBalance + marginUsed
+
+  return {
+    portfolioValue: marginCollateral + spotNonMarginValue + unrealizedPnl,
+    availableMargin: marginCollateral - marginUsed,
+    marginUsed,
+    unrealizedPnl,
+  }
+}