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

package/src/client/createPerpsClient.ts

@@ -1,98 +1,79 @@
 import { PerpsErrorCode } from '@lifi/perps-types'
+import type { Account, WalletClient } from 'viem'
 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'
 
 export const DEFAULT_API_URL = 'https://develop.li.quest/v1/perps'
 
-/**
- * Configuration options for creating a Perps SDK client.
- */
+export interface ProviderConfig {
+  markets?: string[]
+}
+
+/** @deprecated Use ProviderConfig */
+export type HyperliquidConfig = ProviderConfig
+
+export interface ProviderConfigs {
+  [provider: string]: ProviderConfig | undefined
+}
+
 export interface PerpsConfig {
-  /** Integrator identifier (required) */
   integrator: string
-  /** Optional API key for authenticated requests */
-  apiKey?: string
-  /** Base API URL. Defaults to DEFAULT_API_URL */
+  apiKey: string
   apiUrl?: string
-  /** Disable version update check in development mode */
   disableVersionCheck?: boolean
-  /** Custom storage adapter for agent keys. Defaults to localStorage. */
   storage?: StorageAdapter
-  /** Optional request interceptor for custom handling */
   requestInterceptor?: RequestInterceptor
+  providers?: ProviderConfigs
+  /**
+   * Wallet signer used whenever an action's descriptor names the user wallet
+   * in its `signers` list. Accepts any viem-compatible WalletClient:
+   *   - Browser wallet: wagmi's useWalletClient() result
+   *   - Private key:    createWalletClient({ account: privateKeyToAccount('0x...'), transport: http() })
+   *   - Mnemonic:       createWalletClient({ account: mnemonicToAccount('word1 ...'), transport: http() })
+   */
+  signer?: WalletClient<any, any, Account>
 }
 
-/**
- * Resolved configuration with required fields.
- */
 export interface PerpsBaseConfig {
-  /** Integrator identifier (required) */
   integrator: string
-  /** Optional API key for authenticated requests */
-  apiKey?: string
-  /** Resolved API URL (always set) */
+  apiKey: string
   apiUrl: string
-  /** Disable version update check in development mode */
   disableVersionCheck?: boolean
-  /** Optional request interceptor for custom handling */
   requestInterceptor?: RequestInterceptor
+  providers?: ProviderConfigs
 }
 
-/**
- * Request interceptor function type.
- * Called before each request is made, allowing modification of fetch options.
- */
 export type RequestInterceptor = (
   url: string,
   options: RequestInit
 ) => RequestInit | Promise<RequestInit>
 
-/**
- * Options passed to service functions for request control.
- */
 export interface SDKRequestOptions {
-  /** AbortSignal to cancel the request */
   signal?: AbortSignal
+  /**
+   * Lighter auth token for authenticated read endpoints (getOrders, getOrder,
+   * getActivity). Mint via `lighterSigner.createAuthToken(deadline, context)`.
+   * Forwarded as `Authorization: Bearer <token>` and never persisted by the
+   * backend — read-only by design (8h max TTL, cannot authorize writes).
+   */
+  lighterAuthToken?: string
 }
 
-/**
- * The Perps SDK client instance.
- * Holds configuration and agent manager for making API requests.
- */
 export interface PerpsSDKClient {
-  /** SDK configuration */
   readonly config: PerpsBaseConfig
-  /** Agent manager for USER_AGENT signing mode */
   readonly agentManager: AgentManager
+  /** Wallet signer for setup actions — accepts any viem WalletClient (browser, private key, mnemonic). */
+  readonly signer?: WalletClient<any, any, Account>
 }
 
-/**
- * Create a new Perps SDK client.
- *
- * @param options - Configuration options
- * @returns A new SDK client instance
- * @throws {PerpsError} If integrator is not provided
- *
- * @example
- * ```ts
- * const client = createPerpsClient({
- *   integrator: 'my-app',
- *   apiKey: 'optional-api-key',
- * })
- *
- * // Use with service functions
- * const { dexes } = await getDexes(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 +85,7 @@ export function createPerpsClient(options: PerpsConfig): PerpsSDKClient {
     apiUrl,
     disableVersionCheck: options.disableVersionCheck,
     requestInterceptor: options.requestInterceptor,
+    providers: options.providers,
   }
 
   const agentManager = new AgentManager(options.storage)
@@ -115,5 +97,8 @@ export function createPerpsClient(options: PerpsConfig): PerpsSDKClient {
     get agentManager() {
       return agentManager
     },
+    get signer() {
+      return options.signer
+    },
   }
 }

package/src/client/projectAccountConfigSettings.ts

@@ -0,0 +1,39 @@
+import type {
+  AccountConfig,
+  AccountConfigSetting,
+  ProviderOption,
+  ProviderSetup,
+} from '@lifi/perps-types'
+import { projectHyperliquidConfigSettings } from '../providers/hyperliquid/accountConfig.js'
+import { projectLighterConfigSettings } from '../providers/lighter/accountConfig.js'
+import { assertNever } from '../utils/assertNever.js'
+
+/**
+ * Project a typed `AccountConfig` against the provider's `setup` + `options`
+ * descriptors into `AccountConfigSetting[]`.
+ *
+ * Switches on `config.provider` to pick the per-provider mapper. The
+ * `assertNever` exhaustiveness check in the `default` arm forces a compile
+ * error whenever a new variant is added to `AccountConfig`.
+ *
+ * Produces exactly one `AccountConfigSetting` per descriptor in
+ * `setup`-then-`options` order.
+ *
+ * @param config Typed account-state union (discriminated on `provider`).
+ * @param setup  `Provider.setup` from the matching provider metadata.
+ * @param options `Provider.options` from the matching provider metadata.
+ */
+export function projectAccountConfigSettings(
+  config: AccountConfig,
+  setup: ProviderSetup[],
+  options: ProviderOption[]
+): AccountConfigSetting[] {
+  switch (config.provider) {
+    case 'hyperliquid':
+      return projectHyperliquidConfigSettings(config, setup, options)
+    case 'lighter':
+      return projectLighterConfigSettings(config, setup, options)
+    default:
+      return assertNever(config)
+  }
+}

package/src/client/types.ts

@@ -1,22 +1,33 @@
 import type {
+  AccountConfigSetting,
+  AccountResponse,
+  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 {
+  LighterReadOnlyTokenManagerOptions,
+  LighterSignerConfig,
+} from '../signers/lighter/index.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 +38,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 +49,52 @@ export type SigningMode = 'USER' | 'USER_AGENT'
 export interface PerpsClientOptions {
   /** Integrator identifier (required) */
   integrator: string
-  /** Optional API key for authenticated requests */
-  apiKey?: string
+  /** 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
+  /**
+   * Optional Lighter WASM signer configuration. Override the REST URL, chain
+   * ID, or WASM asset locations. Omit to accept defaults (mainnet, chain 304,
+   * WASM assets bundled with the package).
+   */
+  lighter?: LighterSignerConfig
+  /**
+   * Optional Lighter read-only token manager configuration. Override the
+   * Lighter REST URL, inject a custom HTTP fetcher, or pin a clock for
+   * tests. `storage` is shared with the rest of the client unless explicitly
+   * overridden here. Omit to accept the manager's defaults.
+   */
+  lighterReadOnlyToken?: LighterReadOnlyTokenManagerOptions
 }
 
 /**
- * Parameters for building authorization payloads.
+ * Parameters for the internal `buildPrerequisites` helper that materialises
+ * typed-data envelopes for the setup descriptors.
  */
-export interface BuildAuthorizationParams {
-  /** DEX to authorize */
-  dex: string
+export interface CheckPrerequisitesParams {
+  /** Provider to build setup actions 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 */
@@ -92,23 +118,36 @@ export interface PlaceOrderParams {
 }
 
 /**
- * Parameters for building a withdrawal payload.
+ * 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 withdrawing funds.
  */
-export interface BuildWithdrawalParams {
-  /** DEX to withdraw from */
-  dex: string
+export interface WithdrawParams {
+  /** 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 +155,86 @@ export interface CancelOrdersParams {
 }
 
 /**
- * Parameters for getRequiredAuthorizations().
+ * Parameters for modifying orders.
  */
-export interface GetRequiredAuthorizationsParams {
-  /** DEX to check authorizations for */
-  dex: string
+export interface ModifyOrdersParams {
+  /** Provider to modify orders on */
+  provider: string
   /** User wallet address */
   address: Address
+  /** Modifications to apply */
+  modifications: ModifyOrderInput[]
 }
 
 /**
- * Result from getRequiredAuthorizations().
+ * Parameters for {@link PerpsClient.checkSetup}.
  */
-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 GetSetupParams {
+  /** Provider to check setup for */
+  provider: string
+  /** User wallet address */
+  address: Address
+}
+
+/**
+ * Result from {@link PerpsClient.checkSetup}.
+ *
+ * Reports the unsatisfied entries on `Provider.setup` for the queried
+ * account, split by the signer role the descriptor declares.
+ *
+ * `Provider.options` items are NEVER included here — they don't gate trading
+ * and are surfaced separately via `getAccount().settings`.
+ */
+export interface SetupResult {
+  /** Setup steps requiring user wallet signature */
+  userPrerequisites: ActionStep[]
+  /** Setup steps the SDK auto-signs with the agent */
+  agentPrerequisites: ActionStep[]
+  /** Whether all setup items are already satisfied (ready to trade) */
   isReady: boolean
 }
 
 /**
- * Parameters for executeAuthorizations().
+ * Parameters for {@link PerpsClient.satisfySetup}.
  */
-export interface ExecuteAuthorizationsParams {
-  /** DEX to authorize */
-  dex: string
+export interface SatisfySetupParams {
+  /** Provider to satisfy setup for */
+  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 checkSetup() */
+  required: SetupResult
+  /** User-signed actions corresponding to required.userPrerequisites */
+  userSignedActions: SignedActionStep[]
 }
 
 /**
- * Result from executeAuthorizations().
+ * Result from {@link PerpsClient.satisfySetup}.
+ */
+export interface SatisfySetupResult {
+  /** Results from user-signed setup submission */
+  userResults: ExecuteActionResponse
+  /** Results from agent-signed setup submission (if any) */
+  agentResults?: ExecuteActionResponse
+  /**
+   * Fallback user-wallet setup steps surfaced when an agent-signed
+   * `ACCOUNT_MODE` dispatch is not authorised (e.g. Hyperliquid refuses to
+   * upgrade from a non-default abstraction variant without a user signature).
+   * Caller must re-sign these with the user's wallet.
+   */
+  fallbackUserPrerequisites?: ActionStep[]
+}
+
+/**
+ * Result envelope returned by {@link PerpsClient.getAccount} — wraps the
+ * backend's `AccountResponse` with a single SDK-projected `settings` array.
+ *
+ * `settings` contains exactly one `AccountConfigSetting` per descriptor on
+ * `Provider.setup` + `Provider.options` (in that order). Index the
+ * projection by `setting.type === descriptor.type` and read
+ * `setting.values[i].value` for each `Param` the descriptor declared.
  */
-export interface ExecuteAuthorizationsResult {
-  /** Results from user-signed authorization submission */
-  userResults: AuthorizationsResponse
-  /** Results from agent-signed authorization submission (if any) */
-  agentResults?: AuthorizationsResponse
+export interface GetAccountResult extends AccountResponse {
+  /** SDK-projected current state of every setup + options descriptor. */
+  settings: AccountConfigSetting[]
 }

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.',
 }