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

package/src/client/PerpsClient.ts

@@ -1,572 +1,695 @@
 import type {
+  ActionDescriptor,
+  ActionParamsMap,
+  ActionStep,
   Address,
-  AuthorizationsResponse,
-  CancelOrderPayloadResponse,
-  CreateAuthorizationResponse,
-  CreateOrderResponse,
-  CreateWithdrawalResponse,
-  OrderActionType,
-  SignedAuthorization,
-  SignedOrderAction,
-  SubmitOrderResponse,
-  SubmitWithdrawalResponse,
+  AssetIdentity,
+  CreateActionResponse,
+  ExecuteActionResponse,
+  Provider,
+  SignedActionStep,
 } from '@lifi/perps-types'
-import { PerpsErrorCode } from '@lifi/perps-types'
-import { getDexAuthProvider } from '../dex/registry.js'
+import { ActionType, PerpsErrorCode, PerpsSigner } from '@lifi/perps-types'
+import { localStorageAdapter } from '../agent/storage.js'
+import type { StorageAdapter } from '../agent/types.js'
 import { PerpsErrorMessage } from '../errors/constants.js'
 import { PerpsError } from '../errors/PerpsError.js'
-import { cancelOrder } from '../services/cancelOrder.js'
-import { createAuthorization } from '../services/createAuthorization.js'
-import { createOrder } from '../services/createOrder.js'
-import { createWithdrawal } from '../services/createWithdrawal.js'
-import type { SubmitAuthorizationParams } from '../services/submitAuthorization.js'
-import { submitAuthorization } from '../services/submitAuthorization.js'
-import type { SubmitOrderParams } from '../services/submitOrder.js'
-import { submitOrder } from '../services/submitOrder.js'
-import type { SubmitWithdrawalParams } from '../services/submitWithdrawal.js'
-import { submitWithdrawal } from '../services/submitWithdrawal.js'
+import { createAction } from '../services/createAction.js'
+import { executeAction } from '../services/executeAction.js'
+import { getProviders } from '../services/getProviders.js'
 import { signTypedData } from '../utils/signTypedData.js'
 import { createPerpsClient, type PerpsSDKClient } from './createPerpsClient.js'
-import type {
-  BuildAuthorizationParams,
-  BuildWithdrawalParams,
-  CancelOrdersParams,
-  ExecuteAuthorizationsParams,
-  ExecuteAuthorizationsResult,
-  GetRequiredAuthorizationsParams,
-  PerpsClientOptions,
-  PlaceOrderParams,
-  RequiredAuthorizationsResult,
+import {
+  type BuildWithdrawalParams,
+  type CancelOrdersParams,
+  type CheckPrerequisitesParams,
+  type ExecutePrerequisitesParams,
+  type ExecutePrerequisitesResult,
+  type GetPrerequisitesParams,
+  type ModifyOrdersParams,
+  type PerpsClientOptions,
+  type PlaceOrderParams,
+  type PlaceTriggerOrderParams,
+  type PrerequisitesResult,
   SigningMode,
 } from './types.js'
 
-/**
- * Stateful client for managing signing modes and trading operations.
- *
- * The PerpsClient provides two signing modes:
- * - `USER`: User wallet signs each action (wallet popup per action)
- * - `USER_AGENT`: SDK-generated agent signs actions (no popups after setup)
- *
- * In `USER_AGENT` mode, the client:
- * - Generates an agent keypair stored in localStorage (or custom storage)
- * - Auto-injects agent address into authorization requests
- * - Auto-signs trading actions with the agent key
- *
- * @remarks
- * The example below uses Hyperliquid. Authorization keys and parameters are DEX-specific.
- *
- * @example
- * ```ts
- * const perps = new PerpsClient({ integrator: 'my-app' })
- *
- * // Set up agent signing for a user + DEX pair
- * await perps.setSigningMode(userAddress, 'hyperliquid', 'USER_AGENT')
- *
- * // Check and execute required authorizations
- * const required = await perps.getRequiredAuthorizations({
- *   dex: 'hyperliquid',
- *   address: userAddress,
- * })
- *
- * // ... sign actions with user wallet ...
- *
- * // Place orders (agent signs automatically)
- * const result = await perps.placeOrder({
- *   address: userAddress,
- *   dex: 'hyperliquid',
- *   symbol: 'BTC',
- *   side: 'BUY',
- *   type: 'MARKET',
- *   size: '0.1',
- *   price: '95000.00'
- * })
- * ```
- */
 export class PerpsClient {
   private sdkClient: PerpsSDKClient
+  private storage: StorageAdapter
   private signingModes: Map<string, SigningMode> = new Map()
+  private providerMetadataCache: Map<string, Provider> = new Map()
 
   constructor(options: PerpsClientOptions) {
+    this.storage = options.storage ?? localStorageAdapter
     this.sdkClient = createPerpsClient({
       integrator: options.integrator,
       apiKey: options.apiKey,
       apiUrl: options.apiUrl,
-      storage: options.storage,
+      storage: this.storage,
+      providers: options.providers,
     })
   }
 
-  /**
-   * Get the underlying SDK client for use with service functions.
-   */
   get client(): PerpsSDKClient {
     return this.sdkClient
   }
 
-  /**
-   * Get the storage key for a user + DEX pair.
-   */
-  private modeKey(address: Address, dex: string): string {
-    return `${address.toLowerCase()}:${dex.toLowerCase()}`
+  private modeKey(address: Address, provider: string): string {
+    return `${address.toLowerCase()}:${provider.toLowerCase()}`
   }
 
-  /**
-   * Set the signing mode for a user + DEX pair.
-   *
-   * In `USER_AGENT` mode, generates an agent keypair if one doesn't exist.
-   *
-   * @param address - User wallet address
-   * @param dex - DEX identifier
-   * @param mode - Signing mode to set
-   */
-  async setSigningMode(
-    address: Address,
-    dex: string,
-    mode: SigningMode
-  ): Promise<void> {
-    const key = this.modeKey(address, dex)
-    this.signingModes.set(key, mode)
+  private signingModeStorageKey(address: Address, provider: string): string {
+    return `lifi-perps-mode:${address.toLowerCase()}:${provider.toLowerCase()}`
+  }
 
-    if (mode === 'USER_AGENT') {
-      // Generate agent keypair if not exists
-      await this.sdkClient.agentManager.getOrCreateAgent(address, dex)
+  private async getProviderMetadata(provider: string): Promise<Provider> {
+    const cached = this.providerMetadataCache.get(provider)
+    if (cached) {
+      return cached
+    }
+
+    const { providers } = await getProviders(this.sdkClient)
+    for (const d of providers) {
+      this.providerMetadataCache.set(d.key, d)
     }
-  }
 
-  /**
-   * Get the current signing mode for a user + DEX pair.
-   * Defaults to `USER` if not set.
-   */
-  getSigningMode(address: Address, dex: string): SigningMode {
-    return this.signingModes.get(this.modeKey(address, dex)) ?? 'USER'
+    const metadata = this.providerMetadataCache.get(provider)
+    if (!metadata) {
+      const error = new PerpsError(
+        PerpsErrorCode.SDKError,
+        `Unsupported provider: ${provider}`
+      )
+      error.tool = '@lifi/perps-sdk'
+      throw error
+    }
+    return metadata
   }
 
-  /**
-   * Get the agent address for a user + DEX pair.
-   *
-   * @throws {PerpsError} If in USER mode or agent not found
-   */
-  async getAgentAddress(address: Address, dex: string): Promise<Address> {
-    const agent = await this.sdkClient.agentManager.getAgent(address, dex)
-    return agent.address
+  private buildPrerequisiteInputs(
+    prerequisites: ActionDescriptor[],
+    mode: SigningMode,
+    agentAddress?: Address
+  ): Array<{ key: string; params?: Record<string, unknown> }> {
+    return prerequisites
+      .filter((p) => {
+        if (mode === SigningMode.USER) {
+          if (!p.signers.includes(PerpsSigner.USER)) {
+            return false
+          }
+          if (p.type === ActionType.APPROVE_AGENT) {
+            return false
+          }
+          return true
+        }
+        if (
+          p.signers.includes(PerpsSigner.USER) &&
+          !p.signers.includes(PerpsSigner.AGENT) &&
+          p.type === ActionType.USER_SET_ABSTRACTION
+        ) {
+          return false
+        }
+        return true
+      })
+      .map((p) => {
+        const params: Record<string, unknown> = {}
+        if (p.type === ActionType.APPROVE_AGENT && agentAddress) {
+          params.agentAddress = agentAddress
+        }
+        return {
+          key: p.type,
+          ...(Object.keys(params).length > 0 ? { params } : {}),
+        }
+      })
   }
 
-  /**
-   * Check if an agent exists for a user + DEX pair.
-   */
-  async hasAgent(address: Address, dex: string): Promise<boolean> {
-    return this.sdkClient.agentManager.hasAgent(address, dex)
-  }
-
-  /**
-   * Remove the agent for a user + DEX pair.
-   * Also resets signing mode to USER.
-   */
-  async removeAgent(address: Address, dex: string): Promise<void> {
-    await this.sdkClient.agentManager.removeAgent(address, dex)
-    this.signingModes.delete(this.modeKey(address, dex))
-  }
-
-  /**
-   * Build authorization payloads for signing.
-   *
-   * In `USER` mode, `signerAddress` is omitted (backend defaults to `address`).
-   * In `USER_AGENT` mode, auto-injects the agent address as `signerAddress`.
-   *
-   * @param params - Authorization parameters
-   * @returns Authorization actions with typed data for signing
-   */
-  async buildAuthorization(
-    params: BuildAuthorizationParams
-  ): Promise<CreateAuthorizationResponse> {
-    const mode = this.getSigningMode(params.address, params.dex)
-    let { signerAddress } = params
+  private async resolveSignerForAction(
+    action: ActionType,
+    address: Address,
+    provider: string
+  ): Promise<Address | undefined> {
+    const mode = await this.loadSigningMode(address, provider)
+    if (mode !== SigningMode.USER_AGENT) {
+      return undefined
+    }
 
-    if (mode === 'USER_AGENT') {
-      const agent = await this.sdkClient.agentManager.getAgent(
-        params.address,
-        params.dex
-      )
-      signerAddress = signerAddress ?? agent.address
+    // Check if this action supports agent signing
+    const metadata = await this.getProviderMetadata(provider)
+    const allActions = [...metadata.prepareAccountActions, ...metadata.actions]
+    const descriptor = allActions.find((d) => d.type === action)
+    if (!descriptor?.signers.includes(PerpsSigner.AGENT)) {
+      return undefined
     }
 
-    return createAuthorization(this.sdkClient, {
-      ...params,
-      signerAddress,
-    })
+    const agent = await this.sdkClient.agentManager.getAgent(address, provider)
+    return agent.address
   }
 
-  /**
-   * Submit signed authorizations.
-   *
-   * In `USER` mode, `signerAddress` is omitted (backend defaults to `address`).
-   * In `USER_AGENT` mode, auto-injects the agent address as `signerAddress`.
-   *
-   * @param params - Signed authorization parameters
-   */
-  async submitAuthorizations(
-    params: SubmitAuthorizationParams
-  ): Promise<AuthorizationsResponse> {
-    const mode = this.getSigningMode(params.address, params.dex)
-    let { signerAddress } = params
-
-    if (mode === 'USER_AGENT') {
-      const agent = await this.sdkClient.agentManager.getAgent(
-        params.address,
-        params.dex
+  private requireAgentMode(address: Address, provider: string, method: string) {
+    const mode = this.getSigningMode(address, provider)
+    if (mode !== SigningMode.USER_AGENT) {
+      const error = new PerpsError(
+        PerpsErrorCode.SDKError,
+        `${PerpsErrorMessage.InvalidSigningMode} ${method} requires USER_AGENT mode.`
       )
-      signerAddress = signerAddress ?? agent.address
+      error.tool = '@lifi/perps-sdk'
+      throw error
     }
-
-    return submitAuthorization(this.sdkClient, { ...params, signerAddress })
   }
 
-  /**
-   * Build order payloads for signing.
-   *
-   * In `USER` mode, `signerAddress` is omitted (backend defaults to `address`).
-   * In `USER_AGENT` mode, auto-injects the agent address as `signerAddress`.
-   *
-   * @param params - Order parameters
-   * @returns Order actions with typed data for signing
-   */
-  async buildOrder(params: PlaceOrderParams): Promise<CreateOrderResponse> {
-    const mode = this.getSigningMode(params.address, params.dex)
-    let signerAddress: Address | undefined
+  private async autoSignAndExecute(
+    provider: string,
+    address: Address,
+    action: ActionType,
+    actions: ActionStep[]
+  ): Promise<ExecuteActionResponse> {
+    const agent = await this.sdkClient.agentManager.getAgent(address, provider)
 
-    if (mode === 'USER_AGENT') {
-      const agent = await this.sdkClient.agentManager.getAgent(
-        params.address,
-        params.dex
-      )
-      signerAddress = agent.address
-    }
+    const signedActions: SignedActionStep[] = await Promise.all(
+      actions.map(async (a) => ({
+        action: a.action,
+        typedData: a.typedData,
+        signature: await signTypedData(agent.privateKey, a.typedData),
+      }))
+    )
 
-    return createOrder(this.sdkClient, {
-      dex: params.dex,
-      address: params.address,
-      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,
+    return executeAction(this.sdkClient, {
+      provider,
+      address,
+      signerAddress: agent.address,
+      action,
+      actions: signedActions,
     })
   }
 
-  /**
-   * Build cancel order payloads for signing.
-   *
-   * In `USER` mode, `signerAddress` is omitted (backend defaults to `address`).
-   * In `USER_AGENT` mode, auto-injects the agent address as `signerAddress`.
-   *
-   * @param params - Cancel parameters
-   * @returns Cancel actions with typed data for signing
-   */
-  async buildCancelOrder(
-    params: CancelOrdersParams
-  ): Promise<CancelOrderPayloadResponse> {
-    const mode = this.getSigningMode(params.address, params.dex)
-    let signerAddress: Address | undefined
+  // ---------------------------------------------------------------------------
+  // Generic action helpers
+  // ---------------------------------------------------------------------------
 
-    if (mode === 'USER_AGENT') {
-      const agent = await this.sdkClient.agentManager.getAgent(
-        params.address,
-        params.dex
-      )
-      signerAddress = agent.address
-    }
-
-    return cancelOrder(this.sdkClient, {
-      dex: params.dex,
+  async buildAction<T extends ActionType>(
+    action: T,
+    params: { provider: string; address: Address; params: ActionParamsMap[T] }
+  ): Promise<CreateActionResponse> {
+    const signerAddress = await this.resolveSignerForAction(
+      action,
+      params.address,
+      params.provider
+    )
+    return createAction(this.sdkClient, {
+      provider: params.provider,
       address: params.address,
       signerAddress,
-      ids: params.ids,
+      action,
+      params: params.params,
     })
   }
 
-  /**
-   * Place an order with automatic agent signing.
-   *
-   * **Requires USER_AGENT mode.** For USER mode, use `buildOrder()` + `submitSignedOrder()`.
-   *
-   * @param params - Order parameters
-   * @returns Order submission results
-   * @throws {PerpsError} If not in USER_AGENT mode
-   */
-  async placeOrder(params: PlaceOrderParams): Promise<SubmitOrderResponse> {
-    const mode = this.getSigningMode(params.address, params.dex)
-
-    if (mode !== 'USER_AGENT') {
-      throw new PerpsError(
-        PerpsErrorCode.ValidationError,
-        `${PerpsErrorMessage.InvalidSigningMode} placeOrder() requires USER_AGENT mode. Use createOrder() + submitOrder() for USER mode.`
-      )
+  async submitSignedAction(
+    action: ActionType,
+    params: {
+      provider: string
+      address: Address
+      actions: SignedActionStep[]
     }
+  ): Promise<ExecuteActionResponse> {
+    return executeAction(this.sdkClient, { ...params, action })
+  }
 
-    const agent = await this.sdkClient.agentManager.getAgent(
-      params.address,
-      params.dex
-    )
+  // ---------------------------------------------------------------------------
+  // Signing mode management
+  // ---------------------------------------------------------------------------
 
-    // 1. Create order payloads
-    const { actions } = await createOrder(this.sdkClient, {
-      dex: params.dex,
-      address: params.address,
-      signerAddress: agent.address,
-      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,
-    })
+  async setSigningMode(
+    address: Address,
+    provider: string,
+    mode: SigningMode
+  ): Promise<void> {
+    const key = this.modeKey(address, provider)
+    this.signingModes.set(key, mode)
+    await this.storage.set(this.signingModeStorageKey(address, provider), mode)
+    if (mode === SigningMode.USER_AGENT) {
+      await this.sdkClient.agentManager.getOrCreateAgent(address, provider)
+    }
+  }
 
-    // 2. Sign each action with agent key
-    const signedActions: SignedOrderAction[] = await Promise.all(
-      actions.map(async (a) => ({
-        action: a.action,
-        typedData: a.typedData,
-        signature: await signTypedData(agent.privateKey, a.typedData),
-      }))
+  getSigningMode(address: Address, provider: string): SigningMode {
+    return (
+      this.signingModes.get(this.modeKey(address, provider)) ??
+      SigningMode.USER_AGENT
     )
-
-    // 3. Submit
-    return submitOrder(this.sdkClient, {
-      dex: params.dex,
-      address: params.address,
-      signerAddress: agent.address,
-      actions: signedActions,
-    })
   }
 
-  /**
-   * Cancel orders with automatic agent signing.
-   *
-   * **Requires USER_AGENT mode.** For USER mode, use `buildCancelOrder()` + `submitSignedOrder()`.
-   *
-   * @param params - Cancel parameters
-   * @returns Cancel submission results
-   * @throws {PerpsError} If not in USER_AGENT mode
-   */
-  async cancelOrders(params: CancelOrdersParams): Promise<SubmitOrderResponse> {
-    const mode = this.getSigningMode(params.address, params.dex)
-
-    if (mode !== 'USER_AGENT') {
-      throw new PerpsError(
-        PerpsErrorCode.ValidationError,
-        `${PerpsErrorMessage.InvalidSigningMode} cancelOrders() requires USER_AGENT mode. Use cancelOrder() + submitOrder() for USER mode.`
-      )
+  async loadSigningMode(
+    address: Address,
+    provider: string
+  ): Promise<SigningMode> {
+    const key = this.modeKey(address, provider)
+    if (this.signingModes.has(key)) {
+      return this.signingModes.get(key)!
     }
 
-    const agent = await this.sdkClient.agentManager.getAgent(
-      params.address,
-      params.dex
+    const stored = await this.storage.get(
+      this.signingModeStorageKey(address, provider)
     )
+    const mode: SigningMode =
+      stored === SigningMode.USER_AGENT || stored === SigningMode.USER
+        ? stored
+        : SigningMode.USER_AGENT
+    this.signingModes.set(key, mode)
+    return mode
+  }
 
-    // 1. Create cancel payloads
-    const { actions } = await cancelOrder(this.sdkClient, {
-      dex: params.dex,
-      address: params.address,
-      signerAddress: agent.address,
-      ids: params.ids,
-    })
+  async loadAgentMode(address: Address, provider: string): Promise<boolean> {
+    const mode = await this.loadSigningMode(address, provider)
+    return mode === SigningMode.USER_AGENT
+  }
 
-    // 2. Sign each action with agent key
-    const signedActions: SignedOrderAction[] = await Promise.all(
-      actions.map(async (a) => ({
-        action: a.action as OrderActionType,
-        typedData: a.typedData,
-        signature: await signTypedData(agent.privateKey, a.typedData),
-      }))
+  async setAgentMode(
+    address: Address,
+    provider: string,
+    useAgent: boolean
+  ): Promise<void> {
+    await this.setSigningMode(
+      address,
+      provider,
+      useAgent ? SigningMode.USER_AGENT : SigningMode.USER
     )
+  }
 
-    // 3. Submit
-    return submitOrder(this.sdkClient, {
-      dex: params.dex,
-      address: params.address,
-      signerAddress: agent.address,
-      actions: signedActions,
-    })
+  async getAgentAddress(address: Address, provider: string): Promise<Address> {
+    const agent = await this.sdkClient.agentManager.getAgent(address, provider)
+    return agent.address
   }
 
-  /**
-   * Submit pre-signed order actions.
-   *
-   * Use this for USER mode when you've already signed the actions with the user's wallet.
-   * Auto-injects `signerAddress` if not provided (defaults to `address`).
-   *
-   * @param params - Signed order parameters
-   */
-  async submitSignedOrder(
-    params: SubmitOrderParams
-  ): Promise<SubmitOrderResponse> {
-    return submitOrder(this.sdkClient, params)
-  }
-
-  /**
-   * Build a withdrawal payload for the user to sign.
-   *
-   * Withdrawals are user-signed only — agents cannot initiate withdrawals.
-   * No agent injection is performed regardless of signing mode.
-   *
-   * @param params - Withdrawal parameters
-   * @returns Withdrawal action with typed data for signing
-   */
-  async buildWithdrawal(
-    params: BuildWithdrawalParams
-  ): Promise<CreateWithdrawalResponse> {
-    return createWithdrawal(this.sdkClient, {
-      dex: params.dex,
-      address: params.address,
-      withdrawal: params.withdrawal,
-    })
+  async hasAgent(address: Address, provider: string): Promise<boolean> {
+    return this.sdkClient.agentManager.hasAgent(address, provider)
+  }
+
+  async removeAgent(address: Address, provider: string): Promise<void> {
+    await this.sdkClient.agentManager.removeAgent(address, provider)
+    this.signingModes.delete(this.modeKey(address, provider))
+    await this.storage.remove(this.signingModeStorageKey(address, provider))
   }
 
-  /**
-   * Submit a signed withdrawal.
-   *
-   * Withdrawals are user-signed only — agents cannot initiate withdrawals.
-   *
-   * @param params - Signed withdrawal parameters
-   * @returns Withdrawal result
-   */
-  async submitWithdrawal(
-    params: SubmitWithdrawalParams
-  ): Promise<SubmitWithdrawalResponse> {
-    return submitWithdrawal(this.sdkClient, params)
-  }
-
-  /**
-   * Determine which authorizations (if any) the user needs to sign before trading.
-   *
-   * Uses the dex auth provider to determine what authorizations to request,
-   * then calls buildAuthorization — the backend filters already-valid auths
-   * and returns only what's needed.
-   *
-   * @param params - Parameters including dex, address, and dex-specific config
-   * @returns Which authorizations are needed and whether the user is ready to trade
-   */
-  async getRequiredAuthorizations(
-    params: GetRequiredAuthorizationsParams
-  ): Promise<RequiredAuthorizationsResult> {
-    const { dex, address } = params
-    const mode = this.getSigningMode(address, dex)
-    const provider = getDexAuthProvider(dex)
-
-    // Ensure agent exists in USER_AGENT mode
+  // ---------------------------------------------------------------------------
+  // Prerequisites (was: authorizations)
+  // ---------------------------------------------------------------------------
+
+  async checkPrerequisites(
+    params: GetPrerequisitesParams
+  ): Promise<PrerequisitesResult> {
+    const { provider, address } = params
+    const mode = await this.loadSigningMode(address, provider)
+
     let agentAddress: Address | undefined
-    if (mode === 'USER_AGENT') {
+    if (mode === SigningMode.USER_AGENT) {
       const agent = await this.sdkClient.agentManager.getOrCreateAgent(
         address,
-        dex
+        provider
       )
       agentAddress = agent.address
     }
 
-    // Provider declares auth inputs categorized as user/agent
-    const authInputs = provider.getAuthorizationInputs({
-      signingMode: mode,
-      agentAddress,
-    })
+    const metadata = await this.getProviderMetadata(provider)
+    const allInputs = this.buildPrerequisiteInputs(
+      metadata.prepareAccountActions,
+      mode,
+      agentAddress
+    )
 
-    const allInputs = [...authInputs.user, ...authInputs.agent]
     if (allInputs.length === 0) {
-      return { userAuthorizations: [], agentAuthorizations: [], isReady: true }
+      return { userPrerequisites: [], agentPrerequisites: [], isReady: true }
     }
 
-    // Send ALL to backend — it filters already-satisfied ones and returns typed data
-    const { actions } = await this.buildAuthorization({
-      dex,
+    // Build a signer lookup from action descriptors
+    const signersByAction = new Map<string, PerpsSigner[]>()
+    for (const desc of metadata.prepareAccountActions) {
+      signersByAction.set(desc.type, desc.signers)
+    }
+
+    // Send all to backend via createAction for the first prerequisite type
+    // The backend filters already-satisfied ones and returns typed data
+    const { actions } = await this.buildPrerequisites({
+      provider,
       address,
-      authorizations: allInputs,
+      signerAddress: agentAddress,
     })
 
     if (actions.length === 0) {
-      return { userAuthorizations: [], agentAuthorizations: [], isReady: true }
+      return { userPrerequisites: [], agentPrerequisites: [], isReady: true }
     }
 
-    // Categorize backend results using provider's original key sets
-    const agentKeys = new Set(authInputs.agent.map((a) => a.key))
-    const userAuthorizations = actions.filter((a) => !agentKeys.has(a.action))
-    const agentAuthorizations = actions.filter((a) => agentKeys.has(a.action))
+    const userPrerequisites = actions.filter((a) => {
+      const signers = signersByAction.get(a.action) ?? []
+      return signers.includes(PerpsSigner.USER)
+    })
+    const agentPrerequisites = actions.filter((a) => {
+      const signers = signersByAction.get(a.action) ?? []
+      return signers.includes(PerpsSigner.AGENT)
+    })
 
     return {
-      userAuthorizations,
-      agentAuthorizations,
+      userPrerequisites,
+      agentPrerequisites,
       isReady: false,
     }
   }
 
-  /**
-   * Execute authorizations: submit user-signed actions, then auto-sign and submit
-   * any agent authorizations.
-   *
-   * @param params - User-signed actions and the required authorizations result
-   * @returns Combined results from user and agent submissions
-   */
-  async executeAuthorizations(
-    params: ExecuteAuthorizationsParams
-  ): Promise<ExecuteAuthorizationsResult> {
-    const { dex, address, required, userSignedActions } = params
-    const mode = this.getSigningMode(address, dex)
-
-    // 1. Submit user-signed actions (if any)
-    let userResults: AuthorizationsResponse = { results: [] }
+  async buildPrerequisites(
+    params: CheckPrerequisitesParams
+  ): Promise<CreateActionResponse> {
+    const mode = await this.loadSigningMode(params.address, params.provider)
+    let { signerAddress } = params
+
+    if (mode === SigningMode.USER_AGENT && !signerAddress) {
+      const agent = await this.sdkClient.agentManager.getAgent(
+        params.address,
+        params.provider
+      )
+      signerAddress = agent.address
+    }
+
+    const metadata = await this.getProviderMetadata(params.provider)
+    const allInputs = this.buildPrerequisiteInputs(
+      metadata.prepareAccountActions,
+      mode,
+      signerAddress
+    )
+
+    // Use the first prerequisite type as the action type for the batch
+    // The backend handles all prerequisites in a single createPrerequisite call
+    const allActions: ActionStep[] = []
+    for (const input of allInputs) {
+      const { actions } = await createAction(this.sdkClient, {
+        provider: params.provider,
+        address: params.address,
+        signerAddress,
+        action: input.key as ActionType,
+        params: (input.params ?? {}) as Record<string, never>,
+      })
+      allActions.push(...actions)
+    }
+
+    return { actions: allActions }
+  }
+
+  async executePrerequisites(
+    params: ExecutePrerequisitesParams
+  ): Promise<ExecutePrerequisitesResult> {
+    const { provider, address, required, userSignedActions } = params
+    const mode = await this.loadSigningMode(address, provider)
+
+    // 1. Submit user-signed prerequisites
+    let userResults: ExecuteActionResponse = { results: [] }
     if (userSignedActions.length > 0) {
       const signerAddress =
-        mode === 'USER_AGENT'
-          ? (await this.sdkClient.agentManager.getAgent(address, dex)).address
+        mode === SigningMode.USER_AGENT
+          ? (await this.sdkClient.agentManager.getAgent(address, provider))
+              .address
           : address
-      userResults = await submitAuthorization(this.sdkClient, {
-        dex,
+
+      // Submit all user-signed actions — use first action's type for routing
+      const firstAction = required.userPrerequisites[0]?.action as string
+      userResults = await executeAction(this.sdkClient, {
+        provider,
         address,
         signerAddress,
+        action: (firstAction ?? ActionType.APPROVE_AGENT) as ActionType,
         actions: userSignedActions,
       })
 
-      // Check for failures - return early if any user auth failed
-      const failed = userResults.results.find((r) => !r.success)
-      if (failed) {
+      const mandatoryFailure = userResults.results.find((r) => !r.success)
+      if (mandatoryFailure) {
         return { userResults }
       }
     }
 
-    // 2. Auto-sign and submit agent authorizations (if any)
-    // Typed data already built by getRequiredAuthorizations — just sign and submit
-    if (required.agentAuthorizations.length > 0 && mode === 'USER_AGENT') {
-      const agent = await this.sdkClient.agentManager.getAgent(address, dex)
+    // 2. Auto-sign and submit agent prerequisites
+    if (
+      required.agentPrerequisites.length > 0 &&
+      mode === SigningMode.USER_AGENT
+    ) {
+      const agent = await this.sdkClient.agentManager.getAgent(
+        address,
+        provider
+      )
 
-      const signedAgentActions: SignedAuthorization[] = await Promise.all(
-        required.agentAuthorizations.map(async (action) => ({
+      const signedAgentActions: SignedActionStep[] = await Promise.all(
+        required.agentPrerequisites.map(async (action) => ({
           action: action.action,
           typedData: action.typedData,
           signature: await signTypedData(agent.privateKey, action.typedData),
         }))
       )
 
-      const agentResults = await submitAuthorization(this.sdkClient, {
-        dex,
+      const firstAction = required.agentPrerequisites[0]?.action as string
+      const agentResults = await executeAction(this.sdkClient, {
+        provider,
         address,
         signerAddress: agent.address,
+        action: (firstAction ?? ActionType.AGENT_SET_ABSTRACTION) as ActionType,
         actions: signedAgentActions,
       })
 
+      // If AGENT_SET_ABSTRACTION failed (e.g. dexAbstraction → unified upgrade),
+      // fall back to USER_SET_ABSTRACTION so the user can sign it manually.
+      const abstractionFailed = agentResults.results.some(
+        (r) => !r.success && r.action === ActionType.AGENT_SET_ABSTRACTION
+      )
+
+      if (abstractionFailed) {
+        const { actions: fallbackActions } = await createAction(
+          this.sdkClient,
+          {
+            provider,
+            address,
+            action: ActionType.USER_SET_ABSTRACTION,
+            params: {} as ActionParamsMap[ActionType.USER_SET_ABSTRACTION],
+          }
+        )
+
+        if (fallbackActions.length > 0) {
+          return {
+            userResults,
+            agentResults,
+            fallbackUserPrerequisites: fallbackActions,
+          }
+        }
+      }
+
       return { userResults, agentResults }
     }
 
     return { userResults }
   }
+
+  // ---------------------------------------------------------------------------
+  // Trading — build (USER mode) methods
+  // ---------------------------------------------------------------------------
+
+  async buildOrder(params: PlaceOrderParams): Promise<CreateActionResponse> {
+    return this.buildAction(ActionType.PLACE_ORDER, {
+      provider: params.provider,
+      address: params.address,
+      params: {
+        asset: params.asset,
+        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,
+      },
+    })
+  }
+
+  async buildTriggerOrder(
+    params: PlaceTriggerOrderParams
+  ): Promise<CreateActionResponse> {
+    return this.buildAction(ActionType.PLACE_TRIGGER_ORDER, {
+      provider: params.provider,
+      address: params.address,
+      params: {
+        asset: params.asset,
+        side: params.side,
+        takeProfit: params.takeProfit,
+        stopLoss: params.stopLoss,
+      },
+    })
+  }
+
+  async buildCancelOrder(
+    params: CancelOrdersParams
+  ): Promise<CreateActionResponse> {
+    return this.buildAction(ActionType.CANCEL_ORDER, {
+      provider: params.provider,
+      address: params.address,
+      params: { ids: params.ids },
+    })
+  }
+
+  async buildModifyOrder(
+    params: ModifyOrdersParams
+  ): Promise<CreateActionResponse> {
+    return this.buildAction(ActionType.MODIFY_ORDER, {
+      provider: params.provider,
+      address: params.address,
+      params: {
+        modifications: params.modifications,
+      },
+    })
+  }
+
+  async buildPositionMargin(params: {
+    provider: string
+    address: Address
+    asset: AssetIdentity
+    action: 'add' | 'remove'
+    amount: string
+  }): Promise<CreateActionResponse> {
+    return this.buildAction(ActionType.UPDATE_POSITION_MARGIN, {
+      provider: params.provider,
+      address: params.address,
+      params: {
+        asset: params.asset,
+        action: params.action,
+        amount: params.amount,
+      },
+    })
+  }
+
+  async buildWithdrawal(
+    params: BuildWithdrawalParams
+  ): Promise<CreateActionResponse> {
+    return this.buildAction(ActionType.WITHDRAWAL, {
+      provider: params.provider,
+      address: params.address,
+      params: params.withdrawal,
+    })
+  }
+
+  // ---------------------------------------------------------------------------
+  // Trading — submit signed actions (USER mode)
+  // ---------------------------------------------------------------------------
+
+  async submitSignedOrder(params: {
+    provider: string
+    address: Address
+    actions: SignedActionStep[]
+  }): Promise<ExecuteActionResponse> {
+    return this.submitSignedAction(ActionType.PLACE_ORDER, params)
+  }
+
+  async submitSignedPosition(params: {
+    provider: string
+    address: Address
+    actions: SignedActionStep[]
+  }): Promise<ExecuteActionResponse> {
+    return this.submitSignedAction(ActionType.UPDATE_POSITION_MARGIN, params)
+  }
+
+  async submitWithdrawal(params: {
+    provider: string
+    address: Address
+    action: SignedActionStep
+  }): Promise<ExecuteActionResponse> {
+    return this.submitSignedAction(ActionType.WITHDRAWAL, {
+      provider: params.provider,
+      address: params.address,
+      actions: [params.action],
+    })
+  }
+
+  // ---------------------------------------------------------------------------
+  // Trading — auto-sign (USER_AGENT mode)
+  // ---------------------------------------------------------------------------
+
+  async placeOrder(params: PlaceOrderParams): Promise<ExecuteActionResponse> {
+    await this.loadSigningMode(params.address, params.provider)
+    this.requireAgentMode(params.address, params.provider, 'placeOrder()')
+
+    const { actions } = await this.buildOrder(params)
+    return this.autoSignAndExecute(
+      params.provider,
+      params.address,
+      ActionType.PLACE_ORDER,
+      actions
+    )
+  }
+
+  async placeTriggerOrder(
+    params: PlaceTriggerOrderParams
+  ): Promise<ExecuteActionResponse> {
+    await this.loadSigningMode(params.address, params.provider)
+    this.requireAgentMode(
+      params.address,
+      params.provider,
+      'placeTriggerOrder()'
+    )
+
+    const { actions } = await this.buildTriggerOrder(params)
+    return this.autoSignAndExecute(
+      params.provider,
+      params.address,
+      ActionType.PLACE_TRIGGER_ORDER,
+      actions
+    )
+  }
+
+  async cancelOrders(
+    params: CancelOrdersParams
+  ): Promise<ExecuteActionResponse> {
+    await this.loadSigningMode(params.address, params.provider)
+    this.requireAgentMode(params.address, params.provider, 'cancelOrders()')
+
+    const { actions } = await this.buildCancelOrder(params)
+    return this.autoSignAndExecute(
+      params.provider,
+      params.address,
+      ActionType.CANCEL_ORDER,
+      actions
+    )
+  }
+
+  async modifyOrders(
+    params: ModifyOrdersParams
+  ): Promise<ExecuteActionResponse> {
+    await this.loadSigningMode(params.address, params.provider)
+    this.requireAgentMode(params.address, params.provider, 'modifyOrders()')
+
+    const { actions } = await this.buildModifyOrder(params)
+    return this.autoSignAndExecute(
+      params.provider,
+      params.address,
+      ActionType.MODIFY_ORDER,
+      actions
+    )
+  }
+
+  async updatePositionMargin(params: {
+    provider: string
+    address: Address
+    asset: AssetIdentity
+    action: 'add' | 'remove'
+    amount: string
+  }): Promise<ExecuteActionResponse> {
+    await this.loadSigningMode(params.address, params.provider)
+    this.requireAgentMode(
+      params.address,
+      params.provider,
+      'updatePositionMargin()'
+    )
+
+    const { actions } = await this.buildPositionMargin(params)
+    return this.autoSignAndExecute(
+      params.provider,
+      params.address,
+      ActionType.UPDATE_POSITION_MARGIN,
+      actions
+    )
+  }
 }