@lifi/perps-sdk 0.1.1-alpha.0

package/src/errors/utils/rootCause.ts

@@ -0,0 +1,112 @@
+/**
+ * Get the root cause of an error by following the cause chain.
+ *
+ * @param error - The error to get the root cause of
+ * @returns The root cause error, or the original error if no cause chain
+ *
+ * @example
+ * ```ts
+ * const wrapper = new PerpsSDKError(new HTTPError(response, url))
+ * const root = getRootCause(wrapper) // Returns the HTTPError
+ * ```
+ */
+export function getRootCause(error: Error): Error {
+  let current: Error = error
+  let iterations = 0
+  const maxIterations = 100 // Prevent infinite loops
+
+  while (current.cause instanceof Error && iterations < maxIterations) {
+    current = current.cause
+    iterations++
+  }
+
+  return current
+}
+
+/**
+ * Get the message from the root cause of an error.
+ *
+ * @param error - The error to get the root cause message from
+ * @returns The root cause message
+ *
+ * @example
+ * ```ts
+ * const wrapper = new PerpsSDKError(new HTTPError(response, url))
+ * const message = getRootCauseMessage(wrapper) // Returns the HTTPError's message
+ * ```
+ */
+export function getRootCauseMessage(error: Error): string {
+  return getRootCause(error).message
+}
+
+/**
+ * Get the full error chain as an array.
+ *
+ * @param error - The error to get the chain from
+ * @returns Array of errors from outermost to root cause
+ *
+ * @example
+ * ```ts
+ * const chain = getErrorChain(sdkError)
+ * // [PerpsSDKError, HTTPError, ...]
+ * ```
+ */
+export function getErrorChain(error: Error): Error[] {
+  const chain: Error[] = [error]
+  let current = error
+  let iterations = 0
+  const maxIterations = 100
+
+  while (current.cause instanceof Error && iterations < maxIterations) {
+    chain.push(current.cause)
+    current = current.cause
+    iterations++
+  }
+
+  return chain
+}
+
+/**
+ * Check if an error chain contains an error of a specific type.
+ *
+ * @param error - The error to check
+ * @param ErrorClass - The error class to look for
+ * @returns True if the chain contains an error of the specified type
+ *
+ * @example
+ * ```ts
+ * if (hasErrorType(error, HTTPError)) {
+ *   // Handle HTTP error specifically
+ * }
+ * ```
+ */
+export function hasErrorType<T extends Error>(
+  error: Error,
+  ErrorClass: new (...args: any[]) => T
+): boolean {
+  const chain = getErrorChain(error)
+  return chain.some((e) => e instanceof ErrorClass)
+}
+
+/**
+ * Find the first error of a specific type in the error chain.
+ *
+ * @param error - The error to search
+ * @param ErrorClass - The error class to find
+ * @returns The first matching error, or undefined if not found
+ *
+ * @example
+ * ```ts
+ * const httpError = findErrorType(error, HTTPError)
+ * if (httpError) {
+ *   console.log(httpError.status)
+ * }
+ * ```
+ */
+export function findErrorType<T extends Error>(
+  error: Error,
+  ErrorClass: new (...args: any[]) => T
+): T | undefined {
+  const chain = getErrorChain(error)
+  return chain.find((e): e is T => e instanceof ErrorClass)
+}

package/src/index.ts

@@ -0,0 +1,77 @@
+// Client
+
+// Types
+export * from '@lifi/perps-types'
+// Agent
+export { AgentManager } from './agent/AgentManager.js'
+export { createMemoryStorage, localStorageAdapter } from './agent/storage.js'
+export type { Agent, StorageAdapter } from './agent/types.js'
+export type {
+  PerpsBaseConfig,
+  PerpsConfig,
+  PerpsSDKClient,
+  RequestInterceptor,
+  SDKRequestOptions,
+} from './client/createPerpsClient.js'
+export { createPerpsClient } from './client/createPerpsClient.js'
+export { PerpsClient } from './client/PerpsClient.js'
+export type {
+  BuildAuthorizationParams,
+  CancelOrdersParams,
+  ExecuteAuthorizationsParams,
+  ExecuteAuthorizationsResult,
+  GetRequiredAuthorizationsParams,
+  PerpsClientOptions,
+  PlaceOrderParams,
+  RequiredAuthorizationsResult,
+  SigningMode,
+} from './client/types.js'
+export { AgentError } from './errors/AgentError.js'
+export { PerpsErrorMessage, PerpsErrorName } from './errors/constants.js'
+// Errors
+export { HTTPError } from './errors/HTTPError.js'
+export { PerpsError } from './errors/PerpsError.js'
+export { PerpsSDKError } from './errors/PerpsSDKError.js'
+export { ServerError } from './errors/ServerError.js'
+export {
+  findErrorType,
+  getErrorChain,
+  getRootCause,
+  getRootCauseMessage,
+  hasErrorType,
+} from './errors/utils/rootCause.js'
+export { ValidationError } from './errors/ValidationError.js'
+export type { CancelOrderParams } from './services/cancelOrder.js'
+// Services
+export { cancelOrder } from './services/cancelOrder.js'
+export type { CreateAuthorizationParams } from './services/createAuthorization.js'
+export { createAuthorization } from './services/createAuthorization.js'
+export type { CreateOrderParams } from './services/createOrder.js'
+export { createOrder } from './services/createOrder.js'
+export type { GetAccountParams } from './services/getAccount.js'
+export { getAccount } from './services/getAccount.js'
+export { getDexes } from './services/getDexes.js'
+export type { GetHistoryParams } from './services/getHistory.js'
+export { getHistory } from './services/getHistory.js'
+export type { GetMarketParams } from './services/getMarket.js'
+export { getMarket } from './services/getMarket.js'
+export type { GetMarketsParams } from './services/getMarkets.js'
+export { getMarkets } from './services/getMarkets.js'
+export type { GetOhlcvParams } from './services/getOhlcv.js'
+export { getOhlcv } from './services/getOhlcv.js'
+export type { GetOrderParams } from './services/getOrder.js'
+export { getOrder } from './services/getOrder.js'
+export type { GetOrderbookParams } from './services/getOrderbook.js'
+export { getOrderbook } from './services/getOrderbook.js'
+export type { GetPricesParams } from './services/getPrices.js'
+export { getPrices } from './services/getPrices.js'
+export type { SubmitAuthorizationParams } from './services/submitAuthorization.js'
+export { submitAuthorization } from './services/submitAuthorization.js'
+export type { SubmitOrderParams } from './services/submitOrder.js'
+export { submitOrder } from './services/submitOrder.js'
+
+// Utils
+export { signTypedData } from './utils/signTypedData.js'
+
+// Version
+export { name, version } from './version.js'

package/src/services/cancelOrder.ts

@@ -0,0 +1,75 @@
+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

@@ -0,0 +1,75 @@
+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
+ *
+ * @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

@@ -0,0 +1,113 @@
+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
+ *
+ * @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/getAccount.ts

@@ -0,0 +1,47 @@
+import type { AccountResponse, Address } from '@lifi/perps-types'
+import type {
+  PerpsSDKClient,
+  SDKRequestOptions,
+} from '../client/createPerpsClient.js'
+import { buildUrl, request } from '../utils/request.js'
+
+export interface GetAccountParams {
+  /** DEX to get account from (e.g., 'hyperliquid') */
+  dex: string
+  /** Wallet address */
+  address: Address
+}
+
+/**
+ * Get account information including balances, positions, and open orders.
+ *
+ * @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 network or parsing errors
+ *
+ * @example
+ * ```ts
+ * const client = createPerpsClient({ integrator: 'my-app' })
+ * const account = await getAccount(client, {
+ *   dex: '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(
+  client: PerpsSDKClient,
+  params: GetAccountParams,
+  options?: SDKRequestOptions
+): Promise<AccountResponse> {
+  const url = buildUrl(`${client.config.apiUrl}/account`, {
+    dex: params.dex,
+    address: params.address,
+  })
+  return request<AccountResponse>(client.config, url, {}, options)
+}

package/src/services/getDexes.ts

@@ -0,0 +1,34 @@
+import type { DexesResponse } from '@lifi/perps-types'
+import type {
+  PerpsSDKClient,
+  SDKRequestOptions,
+} from '../client/createPerpsClient.js'
+import { request } from '../utils/request.js'
+
+/**
+ * Get all available DEXes.
+ *
+ * @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
+ * @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', ... }]
+ * ```
+ */
+export async function getDexes(
+  client: PerpsSDKClient,
+  options?: SDKRequestOptions
+): Promise<DexesResponse> {
+  return request<DexesResponse>(
+    client.config,
+    `${client.config.apiUrl}/dexes`,
+    {},
+    options
+  )
+}

package/src/services/getHistory.ts

@@ -0,0 +1,62 @@
+import type { Address, HistoryResponse } 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
+  /** Wallet address */
+  address: Address
+  /** Maximum number of items to return */
+  limit?: number
+  /** Cursor for pagination */
+  cursor?: string
+}
+
+/**
+ * Get order history 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
+ * @throws {PerpsError} On network or parsing errors
+ *
+ * @example
+ * ```ts
+ * const client = createPerpsClient({ integrator: 'my-app' })
+ * const { items, pagination } = await getHistory(client, {
+ *   dex: 'hyperliquid',
+ *   address: '0x1234...',
+ *   limit: 50
+ * })
+ *
+ * console.log(items) // [{ id: '123', symbol: 'BTC', status: 'FILLED', ... }]
+ *
+ * // Fetch next page
+ * if (pagination.hasMore) {
+ *   const nextPage = await getHistory(client, {
+ *     dex: 'hyperliquid',
+ *     address: '0x1234...',
+ *     cursor: pagination.cursor
+ *   })
+ * }
+ * ```
+ */
+export async function getHistory(
+  client: PerpsSDKClient,
+  params: GetHistoryParams,
+  options?: SDKRequestOptions
+): Promise<HistoryResponse> {
+  const url = buildUrl(`${client.config.apiUrl}/history`, {
+    dex: params.dex,
+    address: params.address,
+    limit: params.limit,
+    cursor: params.cursor,
+  })
+  return request<HistoryResponse>(client.config, url, {}, options)
+}

package/src/services/getMarket.ts

@@ -0,0 +1,41 @@
+import type { Market } from '@lifi/perps-types'
+import type {
+  PerpsSDKClient,
+  SDKRequestOptions,
+} from '../client/createPerpsClient.js'
+import { buildUrl, request } from '../utils/request.js'
+
+export interface GetMarketParams {
+  /** DEX to get market from (e.g., 'hyperliquid') */
+  dex: string
+  /** Market symbol (e.g., 'BTC') */
+  symbol: string
+}
+
+/**
+ * Get a specific market by symbol.
+ *
+ * @param client - The SDK client instance
+ * @param params - Request parameters
+ * @param options - Request options (e.g., AbortSignal)
+ * @returns Market details
+ * @throws {HTTPError} On API error responses (e.g., 404 if market not found)
+ * @throws {PerpsError} On network or parsing errors
+ *
+ * @example
+ * ```ts
+ * const client = createPerpsClient({ integrator: 'my-app' })
+ * const market = await getMarket(client, { dex: 'hyperliquid', symbol: 'BTC' })
+ * console.log(market) // { symbol: 'BTC', markPrice: '95000.00', ... }
+ * ```
+ */
+export async function getMarket(
+  client: PerpsSDKClient,
+  params: GetMarketParams,
+  options?: SDKRequestOptions
+): Promise<Market> {
+  const url = buildUrl(`${client.config.apiUrl}/markets/${params.symbol}`, {
+    dex: params.dex,
+  })
+  return request<Market>(client.config, url, {}, options)
+}

package/src/services/getMarkets.ts

@@ -0,0 +1,37 @@
+import type { MarketsResponse } from '@lifi/perps-types'
+import type {
+  PerpsSDKClient,
+  SDKRequestOptions,
+} from '../client/createPerpsClient.js'
+import { buildUrl, request } from '../utils/request.js'
+
+export interface GetMarketsParams {
+  /** DEX to get markets from (e.g., 'hyperliquid') */
+  dex: string
+}
+
+/**
+ * Get all available markets for a DEX.
+ *
+ * @param client - The SDK client instance
+ * @param params - Request parameters
+ * @param options - Request options (e.g., AbortSignal)
+ * @returns List of available markets
+ * @throws {HTTPError} On API error responses
+ * @throws {PerpsError} On network or parsing errors
+ *
+ * @example
+ * ```ts
+ * const client = createPerpsClient({ integrator: 'my-app' })
+ * const { markets } = await getMarkets(client, { dex: 'hyperliquid' })
+ * console.log(markets) // [{ symbol: 'BTC', name: 'Bitcoin', ... }]
+ * ```
+ */
+export async function getMarkets(
+  client: PerpsSDKClient,
+  params: GetMarketsParams,
+  options?: SDKRequestOptions
+): Promise<MarketsResponse> {
+  const url = buildUrl(`${client.config.apiUrl}/markets`, { dex: params.dex })
+  return request<MarketsResponse>(client.config, url, {}, options)
+}