@lifi/perps-sdk 0.1.1-alpha.0

package/src/services/getOhlcv.ts

@@ -0,0 +1,58 @@
+import type { OhlcvInterval, OhlcvResponse } from '@lifi/perps-types'
+import type {
+  PerpsSDKClient,
+  SDKRequestOptions,
+} from '../client/createPerpsClient.js'
+import { buildUrl, request } from '../utils/request.js'
+
+export interface GetOhlcvParams {
+  /** DEX to get OHLCV from (e.g., 'hyperliquid') */
+  dex: string
+  /** Market symbol (e.g., 'BTC') */
+  symbol: string
+  /** Candle interval */
+  interval: OhlcvInterval
+  /** Start time (Unix timestamp in milliseconds) */
+  startTime?: number
+  /** End time (Unix timestamp in milliseconds) */
+  endTime?: number
+  /** Maximum number of candles to return */
+  limit?: number
+}
+
+/**
+ * Get OHLCV (candlestick) data for a market.
+ *
+ * @param client - The SDK client instance
+ * @param params - Request parameters
+ * @param options - Request options (e.g., AbortSignal)
+ * @returns OHLCV candle data
+ * @throws {HTTPError} 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',
+ *   symbol: 'BTC',
+ *   interval: '1h',
+ *   limit: 100
+ * })
+ * console.log(candles) // [{ t: 1704067200000, o: '94000', h: '95000', ... }]
+ * ```
+ */
+export async function getOhlcv(
+  client: PerpsSDKClient,
+  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,
+  })
+  return request<OhlcvResponse>(client.config, url, {}, options)
+}

package/src/services/getOrder.ts

@@ -0,0 +1,48 @@
+import type { Address, Order } from '@lifi/perps-types'
+import type {
+  PerpsSDKClient,
+  SDKRequestOptions,
+} from '../client/createPerpsClient.js'
+import { buildUrl, request } from '../utils/request.js'
+
+export interface GetOrderParams {
+  /** DEX to get order from (e.g., 'hyperliquid') */
+  dex: string
+  /** Wallet address */
+  address: Address
+  /** Order ID */
+  id: string
+}
+
+/**
+ * Get a specific order by ID.
+ *
+ * @param client - The SDK client instance
+ * @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 network or parsing errors
+ *
+ * @example
+ * ```ts
+ * const client = createPerpsClient({ integrator: 'my-app' })
+ * const order = await getOrder(client, {
+ *   dex: 'hyperliquid',
+ *   address: '0x1234...',
+ *   id: '123456'
+ * })
+ * console.log(order) // { orderId: '123456', status: 'FILLED', ... }
+ * ```
+ */
+export async function getOrder(
+  client: PerpsSDKClient,
+  params: GetOrderParams,
+  options?: SDKRequestOptions
+): Promise<Order> {
+  const url = buildUrl(`${client.config.apiUrl}/order/${params.id}`, {
+    dex: params.dex,
+    address: params.address,
+  })
+  return request<Order>(client.config, url, {}, options)
+}

package/src/services/getOrderbook.ts

@@ -0,0 +1,49 @@
+import type { OrderbookResponse } from '@lifi/perps-types'
+import type {
+  PerpsSDKClient,
+  SDKRequestOptions,
+} from '../client/createPerpsClient.js'
+import { buildUrl, request } from '../utils/request.js'
+
+export interface GetOrderbookParams {
+  /** DEX to get orderbook from (e.g., 'hyperliquid') */
+  dex: string
+  /** Market symbol (e.g., 'BTC') */
+  symbol: string
+  /** Number of levels to return (default varies by DEX) */
+  depth?: number
+}
+
+/**
+ * Get orderbook for a market.
+ *
+ * @param client - The SDK client instance
+ * @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 network or parsing errors
+ *
+ * @example
+ * ```ts
+ * const client = createPerpsClient({ integrator: 'my-app' })
+ * const { bids, asks } = await getOrderbook(client, {
+ *   dex: 'hyperliquid',
+ *   symbol: 'BTC',
+ *   depth: 20
+ * })
+ * console.log(bids[0]) // { price: '94999.50', size: '1.5' }
+ * console.log(asks[0]) // { price: '95000.50', size: '2.0' }
+ * ```
+ */
+export async function getOrderbook(
+  client: PerpsSDKClient,
+  params: GetOrderbookParams,
+  options?: SDKRequestOptions
+): Promise<OrderbookResponse> {
+  const url = buildUrl(`${client.config.apiUrl}/orderbook/${params.symbol}`, {
+    dex: params.dex,
+    depth: params.depth,
+  })
+  return request<OrderbookResponse>(client.config, url, {}, options)
+}

package/src/services/getPrices.ts

@@ -0,0 +1,48 @@
+import type { PricesResponse } from '@lifi/perps-types'
+import type {
+  PerpsSDKClient,
+  SDKRequestOptions,
+} from '../client/createPerpsClient.js'
+import { buildUrl, request } from '../utils/request.js'
+
+export interface GetPricesParams {
+  /** DEX to get prices from (e.g., 'hyperliquid') */
+  dex: string
+  /** Optional list of symbols to filter (e.g., ['BTC', 'ETH']) */
+  symbols?: string[]
+}
+
+/**
+ * Get current prices for markets.
+ *
+ * @param client - The SDK client instance
+ * @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 network or parsing errors
+ *
+ * @example
+ * ```ts
+ * const client = createPerpsClient({ integrator: 'my-app' })
+ * const { prices } = await getPrices(client, { dex: 'hyperliquid' })
+ * console.log(prices) // { BTC: '95000.00', ETH: '3400.00', ... }
+ *
+ * // Filter by symbols
+ * const { prices } = await getPrices(client, {
+ *   dex: 'hyperliquid',
+ *   symbols: ['BTC', 'ETH']
+ * })
+ * ```
+ */
+export async function getPrices(
+  client: PerpsSDKClient,
+  params: GetPricesParams,
+  options?: SDKRequestOptions
+): Promise<PricesResponse> {
+  const url = buildUrl(`${client.config.apiUrl}/prices`, {
+    dex: params.dex,
+    symbols: params.symbols?.join(','),
+  })
+  return request<PricesResponse>(client.config, url, {}, options)
+}

package/src/services/submitAuthorization.ts

@@ -0,0 +1,70 @@
+import type {
+  Address,
+  AuthorizationsResponse,
+  SignedAuthorization,
+} from '@lifi/perps-types'
+import type {
+  PerpsSDKClient,
+  SDKRequestOptions,
+} from '../client/createPerpsClient.js'
+import { request } from '../utils/request.js'
+
+export interface SubmitAuthorizationParams {
+  /** 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
+  /** Signed authorization actions */
+  actions: SignedAuthorization[]
+}
+
+/**
+ * Submit signed authorizations to the DEX.
+ *
+ * @param client - The SDK client instance
+ * @param params - Request parameters
+ * @param options - Request options (e.g., AbortSignal)
+ * @returns Results for each authorization action
+ * @throws {HTTPError} On API error responses
+ * @throws {PerpsError} On network or parsing errors
+ *
+ * @example
+ * ```ts
+ * const client = createPerpsClient({ integrator: 'my-app' })
+ * const { results } = await submitAuthorization(client, {
+ *   dex: 'hyperliquid',
+ *   address: '0x1234...',
+ *   actions: signedActions
+ * })
+ *
+ * for (const result of results) {
+ *   if (result.success) {
+ *     console.log(`${result.action} authorized`)
+ *   } else {
+ *     console.error(`${result.action} failed: ${result.error}`)
+ *   }
+ * }
+ * ```
+ */
+export async function submitAuthorization(
+  client: PerpsSDKClient,
+  params: SubmitAuthorizationParams,
+  options?: SDKRequestOptions
+): Promise<AuthorizationsResponse> {
+  return request<AuthorizationsResponse>(
+    client.config,
+    `${client.config.apiUrl}/authorization`,
+    {
+      method: 'POST',
+      body: JSON.stringify({
+        dex: params.dex,
+        address: params.address,
+        signerAddress: params.signerAddress,
+        actions: params.actions,
+      }),
+    },
+    options
+  )
+}

package/src/services/submitOrder.ts

@@ -0,0 +1,72 @@
+import type {
+  Address,
+  SignedOrderAction,
+  SubmitOrderResponse,
+} from '@lifi/perps-types'
+import type {
+  PerpsSDKClient,
+  SDKRequestOptions,
+} from '../client/createPerpsClient.js'
+import { request } from '../utils/request.js'
+
+export interface SubmitOrderParams {
+  /** DEX to submit order to (e.g., 'hyperliquid') */
+  dex: string
+  /** Wallet address */
+  address: Address
+  /** Address of the signer (for agent mode, this is the agent address) */
+  signerAddress?: Address
+  /** Signed order actions */
+  actions: SignedOrderAction[]
+}
+
+/**
+ * Submit signed order actions to the DEX.
+ *
+ * @param client - The SDK client instance
+ * @param params - Request parameters
+ * @param options - Request options (e.g., AbortSignal)
+ * @returns Results for each order action
+ * @throws {HTTPError} On API error responses
+ * @throws {PerpsError} On network or parsing errors
+ *
+ * @example
+ * ```ts
+ * const client = createPerpsClient({ integrator: 'my-app' })
+ *
+ * // After creating and signing order actions
+ * const { results } = await submitOrder(client, {
+ *   dex: 'hyperliquid',
+ *   address: '0x1234...',
+ *   actions: signedActions
+ * })
+ *
+ * for (const result of results) {
+ *   if (result.success) {
+ *     console.log(`Order placed: ${result.orderId}`)
+ *   } else {
+ *     console.error(`Order failed: ${result.error}`)
+ *   }
+ * }
+ * ```
+ */
+export async function submitOrder(
+  client: PerpsSDKClient,
+  params: SubmitOrderParams,
+  options?: SDKRequestOptions
+): Promise<SubmitOrderResponse> {
+  return request<SubmitOrderResponse>(
+    client.config,
+    `${client.config.apiUrl}/order`,
+    {
+      method: 'POST',
+      body: JSON.stringify({
+        dex: params.dex,
+        address: params.address,
+        signerAddress: params.signerAddress,
+        actions: params.actions,
+      }),
+    },
+    options
+  )
+}

package/src/utils/request.ts

@@ -0,0 +1,121 @@
+import { PerpsErrorCode } from '@lifi/perps-types'
+import type {
+  PerpsBaseConfig,
+  SDKRequestOptions,
+} from '../client/createPerpsClient.js'
+import { HTTPError } from '../errors/HTTPError.js'
+import { PerpsError } from '../errors/PerpsError.js'
+import { version } from '../version.js'
+import { sleep } from './sleep.js'
+
+export interface RequestOptions extends RequestInit {
+  /** Number of retries on 5xx errors. Default: 1 */
+  retries?: number
+}
+
+const DEFAULT_RETRIES = 1
+
+/**
+ * Make an HTTP request to the Perps API.
+ *
+ * @param config - SDK configuration
+ * @param url - The full URL to request
+ * @param options - Fetch options plus retries
+ * @param sdkOptions - SDK-specific options (signal, etc.)
+ * @returns Parsed JSON response
+ * @throws {HTTPError} On non-2xx responses
+ * @throws {PerpsError} On network or parsing errors
+ */
+export async function request<T>(
+  config: PerpsBaseConfig,
+  url: string,
+  options: RequestOptions = {},
+  sdkOptions?: SDKRequestOptions
+): Promise<T> {
+  // Wait for API health check to pass before making requests
+  if (config.readyPromise) {
+    await config.readyPromise
+  }
+
+  const retries = options.retries ?? DEFAULT_RETRIES
+
+  const headers: Record<string, string> = {
+    'Content-Type': 'application/json',
+    'x-lifi-integrator': config.integrator,
+    'x-lifi-perps-sdk': version,
+    ...(options.headers as Record<string, string>),
+  }
+
+  if (config.apiKey) {
+    headers['x-lifi-api-key'] = config.apiKey
+  }
+
+  // Merge signal from sdkOptions into options
+  let finalOptions: RequestInit = {
+    ...options,
+    headers,
+    signal: sdkOptions?.signal ?? options.signal,
+  }
+
+  // Apply request interceptor if configured
+  if (config.requestInterceptor) {
+    finalOptions = await config.requestInterceptor(url, finalOptions)
+  }
+
+  try {
+    const response = await fetch(url, finalOptions)
+
+    if (!response.ok) {
+      const error = new HTTPError(response, url)
+      await error.buildAdditionalDetails()
+
+      // Retry on 5xx errors
+      if (retries > 0 && response.status >= 500) {
+        await sleep(500)
+        return request<T>(
+          config,
+          url,
+          { ...options, retries: retries - 1 },
+          sdkOptions
+        )
+      }
+
+      throw error
+    }
+
+    return (await response.json()) as T
+  } catch (error) {
+    if (error instanceof HTTPError || error instanceof PerpsError) {
+      throw error
+    }
+
+    // Network error or other fetch failure
+    throw new PerpsError(
+      PerpsErrorCode.ServerError,
+      error instanceof Error ? error.message : 'Request failed'
+    )
+  }
+}
+
+/**
+ * Build a URL with query parameters.
+ *
+ * @param baseUrl - The base URL
+ * @param params - Query parameters (undefined values are filtered out)
+ * @returns Full URL with query string
+ */
+export function buildUrl(
+  baseUrl: string,
+  params: Record<string, string | number | boolean | undefined>
+): string {
+  const searchParams = new URLSearchParams()
+
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== undefined) {
+      searchParams.set(key, String(value))
+    }
+  }
+
+  const queryString = searchParams.toString()
+  return queryString ? `${baseUrl}?${queryString}` : baseUrl
+}

package/src/utils/signTypedData.ts

@@ -0,0 +1,31 @@
+import type { Hex, PerpsTypedData } from '@lifi/perps-types'
+import { privateKeyToAccount } from 'viem/accounts'
+
+/**
+ * Sign EIP-712 typed data with a private key.
+ *
+ * @param privateKey - The private key to sign with
+ * @param typedData - The typed data to sign
+ * @returns The signature as a hex string
+ *
+ * @example
+ * ```ts
+ * const signature = await signTypedData(agentPrivateKey, typedData)
+ * ```
+ */
+export async function signTypedData(
+  privateKey: Hex,
+  typedData: PerpsTypedData
+): Promise<Hex> {
+  const account = privateKeyToAccount(privateKey)
+
+  // viem's signTypedData expects the typed data in a specific format
+  const signature = await account.signTypedData({
+    domain: typedData.domain,
+    types: typedData.types,
+    primaryType: typedData.primaryType,
+    message: typedData.message,
+  })
+
+  return signature
+}

package/src/utils/sleep.ts

@@ -0,0 +1,2 @@
+export const sleep = (ms: number): Promise<void> =>
+  new Promise((resolve) => setTimeout(resolve, ms))

package/src/version.ts

@@ -0,0 +1,2 @@
+export const name = '@lifi/perps-sdk'
+export const version = '0.1.1-alpha.0'