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

package/src/client/createPerpsClient.ts

@@ -1,10 +1,30 @@
 import { PerpsErrorCode } from '@lifi/perps-types'
 import { AgentManager } from '../agent/AgentManager.js'
 import type { StorageAdapter } from '../agent/types.js'
-import { PerpsErrorName } from '../errors/constants.js'
 import { PerpsError } from '../errors/PerpsError.js'
 
-const DEFAULT_API_URL = 'https://li.quest/v1/perps'
+export const DEFAULT_API_URL = 'https://develop.li.quest/v1/perps'
+
+/**
+ * Per-provider configuration.
+ */
+export interface ProviderConfig {
+  /** Markets to include. Filters visible assets and various API calls. */
+  markets?: string[]
+}
+
+/**
+ * Provider-specific configuration for Hyperliquid.
+ * @deprecated Use ProviderConfig instead — this alias exists for backwards compatibility.
+ */
+export type HyperliquidConfig = ProviderConfig
+
+/**
+ * Provider-specific configurations keyed by provider name.
+ */
+export interface ProviderConfigs {
+  [provider: string]: ProviderConfig | undefined
+}
 
 /**
  * Configuration options for creating a Perps SDK client.
@@ -12,9 +32,9 @@ const DEFAULT_API_URL = 'https://li.quest/v1/perps'
 export interface PerpsConfig {
   /** Integrator identifier (required) */
   integrator: string
-  /** Optional API key for authenticated requests */
-  apiKey?: string
-  /** Base API URL. Defaults to https://li.quest/v1/perps */
+  /** API key for authenticated requests (get one at https://portal.li.fi/) */
+  apiKey: string
+  /** Base API URL. Defaults to DEFAULT_API_URL */
   apiUrl?: string
   /** Disable version update check in development mode */
   disableVersionCheck?: boolean
@@ -22,6 +42,8 @@ export interface PerpsConfig {
   storage?: StorageAdapter
   /** Optional request interceptor for custom handling */
   requestInterceptor?: RequestInterceptor
+  /** Provider-specific configuration */
+  providers?: ProviderConfigs
 }
 
 /**
@@ -30,14 +52,16 @@ export interface PerpsConfig {
 export interface PerpsBaseConfig {
   /** Integrator identifier (required) */
   integrator: string
-  /** Optional API key for authenticated requests */
-  apiKey?: string
+  /** API key for authenticated requests */
+  apiKey: string
   /** Resolved API URL (always set) */
   apiUrl: string
   /** Disable version update check in development mode */
   disableVersionCheck?: boolean
   /** Optional request interceptor for custom handling */
   requestInterceptor?: RequestInterceptor
+  /** Provider-specific configuration */
+  providers?: ProviderConfigs
 }
 
 /**
@@ -79,20 +103,20 @@ export interface PerpsSDKClient {
  * ```ts
  * const client = createPerpsClient({
  *   integrator: 'my-app',
- *   apiKey: 'optional-api-key',
+ *   apiKey: 'your-api-key',
  * })
  *
  * // Use with service functions
- * const { dexes } = await getDexes(client)
+ * const { providers } = await getProviders(client)
  * ```
  */
 export function createPerpsClient(options: PerpsConfig): PerpsSDKClient {
   if (!options.integrator) {
     const error = new PerpsError(
-      PerpsErrorCode.ValidationError,
+      PerpsErrorCode.SDKError,
       'Integrator is required. Please see documentation at https://docs.li.fi'
     )
-    error.name = PerpsErrorName.ValidationError
+    error.tool = '@lifi/perps-sdk'
     throw error
   }
 
@@ -104,6 +128,7 @@ export function createPerpsClient(options: PerpsConfig): PerpsSDKClient {
     apiUrl,
     disableVersionCheck: options.disableVersionCheck,
     requestInterceptor: options.requestInterceptor,
+    providers: options.providers,
   }
 
   const agentManager = new AgentManager(options.storage)

package/src/client/types.ts

@@ -1,22 +1,27 @@
 import type {
+  ActionStep,
   Address,
-  AuthorizationAction,
-  AuthorizationInput,
-  AuthorizationsResponse,
+  AssetIdentity,
+  ExecuteActionResponse,
+  ModifyOrderInput,
   OrderSide,
   OrderType,
-  SignedAuthorization,
+  SignedActionStep,
   TimeInForce,
   TriggerOrderInput,
-  WithdrawalInput,
+  WithdrawalParams,
 } from '@lifi/perps-types'
 import type { StorageAdapter } from '../agent/types.js'
+import type { ProviderConfigs } from './createPerpsClient.js'
 
 // Re-export the SDK client types from createPerpsClient
 export type {
+  HyperliquidConfig,
   PerpsBaseConfig,
   PerpsConfig,
   PerpsSDKClient,
+  ProviderConfig,
+  ProviderConfigs,
   RequestInterceptor,
   SDKRequestOptions,
 } from './createPerpsClient.js'
@@ -27,7 +32,10 @@ export type {
  * - `USER`: User wallet signs each action (requires wallet popup per action)
  * - `USER_AGENT`: SDK-generated agent signs actions (no popups after initial setup)
  */
-export type SigningMode = 'USER' | 'USER_AGENT'
+export enum SigningMode {
+  USER = 'USER',
+  USER_AGENT = 'USER_AGENT',
+}
 
 /**
  * Options for PerpsClient constructor.
@@ -35,40 +43,38 @@ export type SigningMode = 'USER' | 'USER_AGENT'
 export interface PerpsClientOptions {
   /** Integrator identifier (required) */
   integrator: string
-  /** Optional API key for authenticated requests */
-  apiKey?: string
-  /** Base API URL. Defaults to https://li.quest/v1/perps */
+  /** API key for authenticated requests (get one at https://portal.li.fi/) */
+  apiKey: string
+  /** Base API URL. Defaults to DEFAULT_API_URL */
   apiUrl?: string
   /** Custom storage adapter for agent keys. Defaults to localStorage. */
   storage?: StorageAdapter
+  /** Provider-specific configuration */
+  providers?: ProviderConfigs
 }
 
 /**
- * Parameters for building authorization payloads.
+ * Parameters for checking prerequisites (previously: building authorization payloads).
  */
-export interface BuildAuthorizationParams {
-  /** DEX to authorize */
-  dex: string
+export interface CheckPrerequisitesParams {
+  /** Provider to check prerequisites for */
+  provider: string
   /** User wallet address */
   address: Address
   /** Address of the signer (auto-set in USER_AGENT mode) */
   signerAddress?: Address
-  /** Authorizations to create */
-  authorizations: AuthorizationInput[]
 }
 
 /**
  * Parameters for placing an order.
  */
 export interface PlaceOrderParams {
-  /** DEX to place order on */
-  dex: string
+  /** Provider to place order on */
+  provider: string
   /** User wallet address */
   address: Address
-  /** Client-provided order ID */
-  clientOrderId?: string
-  /** Market symbol */
-  symbol: string
+  /** Asset identity */
+  asset: AssetIdentity
   /** Order side */
   side: OrderSide
   /** Order type */
@@ -91,24 +97,37 @@ export interface PlaceOrderParams {
   stopLoss?: TriggerOrderInput
 }
 
+/**
+ * Parameters for placing trigger-only orders (TP/SL on existing positions).
+ * Sends a TRIGGER_ONLY order that skips the main order wire.
+ */
+export interface PlaceTriggerOrderParams {
+  provider: string
+  address: Address
+  asset: AssetIdentity
+  side: OrderSide
+  takeProfit?: TriggerOrderInput
+  stopLoss?: TriggerOrderInput
+}
+
 /**
  * Parameters for building a withdrawal payload.
  */
 export interface BuildWithdrawalParams {
-  /** DEX to withdraw from */
-  dex: string
+  /** Provider to withdraw from */
+  provider: string
   /** User wallet address (account owner) */
   address: Address
   /** Withdrawal details */
-  withdrawal: WithdrawalInput
+  withdrawal: WithdrawalParams
 }
 
 /**
  * Parameters for canceling orders.
  */
 export interface CancelOrdersParams {
-  /** DEX to cancel orders on */
-  dex: string
+  /** Provider to cancel orders on */
+  provider: string
   /** User wallet address */
   address: Address
   /** Order IDs to cancel */
@@ -116,47 +135,61 @@ export interface CancelOrdersParams {
 }
 
 /**
- * Parameters for getRequiredAuthorizations().
+ * Parameters for modifying orders.
+ */
+export interface ModifyOrdersParams {
+  /** Provider to modify orders on */
+  provider: string
+  /** User wallet address */
+  address: Address
+  /** Modifications to apply */
+  modifications: ModifyOrderInput[]
+}
+
+/**
+ * Parameters for checkPrerequisites().
  */
-export interface GetRequiredAuthorizationsParams {
-  /** DEX to check authorizations for */
-  dex: string
+export interface GetPrerequisitesParams {
+  /** Provider to check prerequisites for */
+  provider: string
   /** User wallet address */
   address: Address
 }
 
 /**
- * Result from getRequiredAuthorizations().
+ * Result from checkPrerequisites().
  */
-export interface RequiredAuthorizationsResult {
-  /** Authorization actions requiring user wallet signature (with typed data for signing) */
-  userAuthorizations: AuthorizationAction[]
-  /** Authorization actions the SDK auto-signs with the agent (with typed data) */
-  agentAuthorizations: AuthorizationAction[]
-  /** Whether all authorizations are already satisfied (ready to trade) */
+export interface PrerequisitesResult {
+  /** Prerequisite steps requiring user wallet signature */
+  userPrerequisites: ActionStep[]
+  /** Prerequisite steps the SDK auto-signs with the agent */
+  agentPrerequisites: ActionStep[]
+  /** Whether all prerequisites are already satisfied (ready to trade) */
   isReady: boolean
 }
 
 /**
- * Parameters for executeAuthorizations().
+ * Parameters for executePrerequisites().
  */
-export interface ExecuteAuthorizationsParams {
-  /** DEX to authorize */
-  dex: string
+export interface ExecutePrerequisitesParams {
+  /** Provider to authorize */
+  provider: string
   /** User wallet address */
   address: Address
-  /** The result from getRequiredAuthorizations() */
-  required: RequiredAuthorizationsResult
-  /** User-signed actions corresponding to required.userAuthorizations */
-  userSignedActions: SignedAuthorization[]
+  /** The result from checkPrerequisites() */
+  required: PrerequisitesResult
+  /** User-signed actions corresponding to required.userPrerequisites */
+  userSignedActions: SignedActionStep[]
 }
 
 /**
- * Result from executeAuthorizations().
+ * Result from executePrerequisites().
  */
-export interface ExecuteAuthorizationsResult {
-  /** Results from user-signed authorization submission */
-  userResults: AuthorizationsResponse
-  /** Results from agent-signed authorization submission (if any) */
-  agentResults?: AuthorizationsResponse
+export interface ExecutePrerequisitesResult {
+  /** Results from user-signed prerequisite submission */
+  userResults: ExecuteActionResponse
+  /** Results from agent-signed prerequisite submission (if any) */
+  agentResults?: ExecuteActionResponse
+  /** Fallback user prerequisites when agent prerequisites fail (e.g. USER_SET_ABSTRACTION when AGENT_SET_ABSTRACTION cannot upgrade from dexAbstraction) */
+  fallbackUserPrerequisites?: ActionStep[]
 }

package/src/errors/PerpsError.ts

@@ -1,34 +1,15 @@
 import { PerpsErrorCode } from '@lifi/perps-types'
-import { version } from '../version.js'
-import { PerpsErrorName } from './constants.js'
 
 export class PerpsError extends Error {
   code: PerpsErrorCode
-  override name = PerpsErrorName.PerpsError
+  override name = 'PerpsError'
+  tool?: string
 
   constructor(
     code: PerpsErrorCode = PerpsErrorCode.DefaultError,
     message = 'Unknown error occurred'
   ) {
-    const errorMessage = `[${PerpsErrorName.PerpsError}] ${message}\nLI.FI Perps SDK version: ${version}`
-    super(errorMessage)
+    super(message)
     this.code = code
-    this.name = PerpsErrorName.PerpsError
-  }
-
-  static fromError(error: unknown, defaultCode?: PerpsErrorCode): PerpsError {
-    if (error instanceof PerpsError) {
-      return error
-    }
-    if (error instanceof Error) {
-      return new PerpsError(
-        defaultCode ?? PerpsErrorCode.DefaultError,
-        error.message
-      )
-    }
-    return new PerpsError(
-      defaultCode ?? PerpsErrorCode.DefaultError,
-      String(error)
-    )
   }
 }

package/src/errors/constants.ts

@@ -1,15 +1,4 @@
-export enum PerpsErrorName {
-  PerpsError = 'PerpsError',
-  HTTPError = 'HTTPError',
-  ValidationError = 'ValidationError',
-  ServerError = 'ServerError',
-  ConfigError = 'ConfigError',
-  AgentError = 'AgentError',
-}
-
 export enum PerpsErrorMessage {
-  UnknownError = 'Unknown error occurred.',
-  ConfigNotInitialized = 'SDK not configured. Call createPerpsConfig() first.',
   AgentNotFound = 'Agent not found. Call setSigningMode() first.',
   InvalidSigningMode = 'Invalid signing mode for this operation.',
 }

package/src/index.ts

@@ -2,6 +2,9 @@
 
 // Types
 export * from '@lifi/perps-types'
+// Utils
+// biome-ignore lint/correctness/useImportExtensions: package subpath export
+export { HlAbstractionMode } from '@lifi/perps-types/providers/hyperliquid'
 // Agent
 export { AgentManager } from './agent/AgentManager.js'
 export { createMemoryStorage, localStorageAdapter } from './agent/storage.js'
@@ -13,76 +16,96 @@ export type {
   RequestInterceptor,
   SDKRequestOptions,
 } from './client/createPerpsClient.js'
-export { createPerpsClient } from './client/createPerpsClient.js'
+export {
+  createPerpsClient,
+  DEFAULT_API_URL,
+} from './client/createPerpsClient.js'
 export { PerpsClient } from './client/PerpsClient.js'
 export type {
-  BuildAuthorizationParams,
   BuildWithdrawalParams,
   CancelOrdersParams,
-  ExecuteAuthorizationsParams,
-  ExecuteAuthorizationsResult,
-  GetRequiredAuthorizationsParams,
+  CheckPrerequisitesParams,
+  ExecutePrerequisitesParams,
+  ExecutePrerequisitesResult,
+  GetPrerequisitesParams,
+  HyperliquidConfig,
+  ModifyOrdersParams,
   PerpsClientOptions,
-  PlaceOrderParams,
-  RequiredAuthorizationsResult,
-  SigningMode,
+  PlaceOrderParams as ClientPlaceOrderParams,
+  PlaceTriggerOrderParams as ClientPlaceTriggerOrderParams,
+  PrerequisitesResult,
+  ProviderConfig,
+  ProviderConfigs,
 } from './client/types.js'
-// Dex
-export { getDexAuthProvider } from './dex/registry.js'
-export type { DexAuthInputs, DexAuthProvider } from './dex/types.js'
-export { AgentError } from './errors/AgentError.js'
-export { PerpsErrorMessage, PerpsErrorName } from './errors/constants.js'
+export { SigningMode } from './client/types.js'
 // Errors
-export { HTTPError } from './errors/HTTPError.js'
+export { PerpsErrorMessage } from './errors/constants.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'
 // Realtime
 export { PerpsWsClient } from './realtime/PerpsWsClient.js'
 export type { EventForSubscription } from './realtime/types.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 { CreateWithdrawalParams } from './services/createWithdrawal.js'
-export { createWithdrawal } from './services/createWithdrawal.js'
+export type { CreateActionParams } from './services/createAction.js'
+export { createAction } from './services/createAction.js'
+export type { ExecuteActionParams } from './services/executeAction.js'
+export { executeAction } from './services/executeAction.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 { GetActivityParams } from './services/getActivity.js'
+export { getActivity } from './services/getActivity.js'
+export type { GetAssetParams } from './services/getAsset.js'
+export { getAsset } from './services/getAsset.js'
+export type { GetAssetsParams } from './services/getAssets.js'
+export { getAssets } from './services/getAssets.js'
+export type { GetFillsParams } from './services/getFills.js'
+export { getFills } from './services/getFills.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 { GetOrdersParams } from './services/getOrders.js'
+export { getOrders } from './services/getOrders.js'
+export type { GetPositionsParams } from './services/getPositions.js'
+export { getPositions } from './services/getPositions.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'
-export type { SubmitWithdrawalParams } from './services/submitWithdrawal.js'
-export { submitWithdrawal } from './services/submitWithdrawal.js'
-
-// Utils
+export { getProviders } from './services/getProviders.js'
+export type { AccountSummary } from './utils/accountSummary.js'
+export { calculateAccountSummary } from './utils/accountSummary.js'
+export type { ExpectedPnl } from './utils/calculations.js'
+export {
+  applySlippage,
+  calculateExpectedPnl,
+  calculateNotionalValue,
+  calculatePositionSize,
+  calculateRealizedPnlPercent,
+  calculateRequiredMargin,
+  calculateRoe,
+  calculateUnrealizedPnl,
+  estimateFees,
+  percentFromPrice,
+  priceFromPercent,
+} from './utils/calculations.js'
+export {
+  calculateLiquidationPrice,
+  calculateMaintenanceMarginRate,
+  formatOrderPrice,
+  formatOrderSize,
+  getMaxPriceDecimals,
+} from './utils/hyperliquid/index.js'
+export {
+  classifyFill,
+  FillClassification,
+  isStopLossOrder,
+  isTakeProfitOrder,
+  isTpSlOrder,
+} from './utils/orderClassification.js'
+export { stringToFloat } from './utils/parse.js'
 export { signTypedData } from './utils/signTypedData.js'
+export { fromBaseUnits, fromBaseUnitsNumber } from './utils/units.js'
+export { validateMargin } from './utils/validation.js'
 
 // Version
 export { name, version } from './version.js'

package/src/realtime/PerpsWsClient.ts

@@ -1,14 +1,17 @@
 import type { Subscription } from '@lifi/perps-types'
 import type { PerpsSDKClient } from '../client/createPerpsClient.js'
-import { getDexes } from '../services/getDexes.js'
-import { getMarkets } from '../services/getMarkets.js'
+import { getProviders } from '../services/getProviders.js'
 import { HyperliquidWsProvider } from './hyperliquid/HyperliquidWsProvider.js'
-import type { EventForSubscription, SubscriptionListener } from './types.js'
+import type {
+  EventForSubscription,
+  SubscriptionListener,
+  WsProvider,
+} from './types.js'
 
 export class PerpsWsClient {
   private readonly client: PerpsSDKClient
-  private providers = new Map<string, HyperliquidWsProvider>()
-  private initPromises = new Map<string, Promise<HyperliquidWsProvider>>()
+  private providers = new Map<string, WsProvider>()
+  private initPromises = new Map<string, Promise<WsProvider>>()
 
   constructor(client: PerpsSDKClient) {
     this.client = client
@@ -18,7 +21,8 @@ export class PerpsWsClient {
     sub: S,
     listener: (event: EventForSubscription<S>) => void
   ): Promise<() => void> {
-    const provider = await this.getOrCreateProvider(sub.dex)
+    const providerKey = sub.dex
+    const provider = await this.getOrCreateProvider(providerKey)
     return provider.subscribe(sub, listener as SubscriptionListener)
   }
 
@@ -30,44 +34,56 @@ export class PerpsWsClient {
     this.initPromises.clear()
   }
 
-  private async getOrCreateProvider(
-    dex: string
-  ): Promise<HyperliquidWsProvider> {
-    const existing = this.providers.get(dex)
+  private async getOrCreateProvider(provider: string): Promise<WsProvider> {
+    const existing = this.providers.get(provider)
     if (existing) {
       return existing
     }
 
-    let initPromise = this.initPromises.get(dex)
+    let initPromise = this.initPromises.get(provider)
     if (!initPromise) {
-      initPromise = this.initProvider(dex)
-      this.initPromises.set(dex, initPromise)
+      initPromise = this.initProvider(provider)
+      this.initPromises.set(provider, initPromise)
     }
     return initPromise
   }
 
-  private async initProvider(dex: string): Promise<HyperliquidWsProvider> {
-    const [{ dexes }, { markets }] = await Promise.all([
-      getDexes(this.client),
-      getMarkets(this.client, { dex }),
-    ])
+  private async initProvider(provider: string): Promise<WsProvider> {
+    const { providers } = await getProviders(this.client)
 
-    const dexInfo = dexes.find((d) => d.key === dex)
-    if (!dexInfo?.wsUrl) {
-      throw new Error(`No WebSocket URL found for dex: ${dex}`)
+    const providerInfo = providers.find((d) => d.key === provider)
+    if (!providerInfo?.wsUrl) {
+      throw new Error(`No WebSocket URL found for provider: ${provider}`)
     }
 
-    const assetIdLookup = new Map<string, number>()
-    for (const m of markets) {
-      assetIdLookup.set(m.symbol, m.assetId)
-    }
+    const allMarkets = (providerInfo.markets ?? []) as Array<{
+      id: string
+    }>
+    const providerConfig = this.client.config.providers?.[provider]
+    const configuredMarkets = providerConfig?.markets
+    const filteredMarkets = configuredMarkets
+      ? allMarkets.filter((m) => configuredMarkets.includes(m.id))
+      : allMarkets
+    const subProviders = filteredMarkets
+      .map((m) => m.id)
+      .filter((id) => id !== provider && id !== 'spot')
 
-    const provider = new HyperliquidWsProvider(
-      dexInfo.wsUrl,
-      dex,
-      assetIdLookup
+    const wsProvider = this.createWsProvider(
+      provider,
+      providerInfo.wsUrl,
+      subProviders
     )
-    this.providers.set(dex, provider)
-    return provider
+    this.providers.set(provider, wsProvider)
+    return wsProvider
+  }
+
+  private createWsProvider(
+    provider: string,
+    wsUrl: string,
+    subProviders: string[]
+  ): WsProvider {
+    // Currently only Hyperliquid has a WS implementation.
+    // Future providers can be added here with their own WsProvider classes.
+    return new HyperliquidWsProvider(wsUrl, provider, subProviders)
   }
 }