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

package/src/client/PerpsClient.ts

@@ -1,572 +1,1397 @@
 import type {
+  ActionDescriptor,
+  ActionParamsMap,
+  ActionStep,
   Address,
-  AuthorizationsResponse,
-  CancelOrderPayloadResponse,
-  CreateAuthorizationResponse,
-  CreateOrderResponse,
-  CreateWithdrawalResponse,
-  OrderActionType,
-  SignedAuthorization,
-  SignedOrderAction,
-  SubmitOrderResponse,
-  SubmitWithdrawalResponse,
+  ApproveReadOnlyTokenParams,
+  AssetIdentity,
+  CreateActionResponse,
+  Eip712ActionStep,
+  Eip712SignedActionStep,
+  EvmTxActionStep,
+  EvmTxSignedActionStep,
+  ExecuteActionResponse,
+  Provider,
+  SignedActionStep,
+  WasmBlobActionStep,
+  WasmBlobSignedActionStep,
 } from '@lifi/perps-types'
-import { PerpsErrorCode } from '@lifi/perps-types'
-import { getDexAuthProvider } from '../dex/registry.js'
-import { PerpsErrorMessage } from '../errors/constants.js'
+import {
+  ActionType,
+  PerpsErrorCode,
+  PerpsSigner,
+  SigningMethod,
+} from '@lifi/perps-types'
+import { parseAbi } from 'viem'
+import { localStorageAdapter } from '../agent/storage.js'
+import type { StorageAdapter } from '../agent/types.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 { signTypedData } from '../utils/signTypedData.js'
+import { createAction } from '../services/createAction.js'
+import { executeAction } from '../services/executeAction.js'
+import { getAccount } from '../services/getAccount.js'
+import { getProviders } from '../services/getProviders.js'
+import {
+  type ApproveReadOnlyTokenResult,
+  DEFAULT_API_KEY_INDEX,
+  type LighterApiKey,
+  LighterKeyStore,
+  LighterReadOnlyTokenManager,
+  type LighterReadOnlyTokenManagerOptions,
+  LighterSigner,
+  type LighterSignerConfig,
+  walletClientSigner,
+} from '../signers/lighter/index.js'
+import {
+  signTypedData,
+  signTypedDataWithSigner,
+} from '../utils/signTypedData.js'
 import { createPerpsClient, type PerpsSDKClient } from './createPerpsClient.js'
-import type {
-  BuildAuthorizationParams,
-  BuildWithdrawalParams,
-  CancelOrdersParams,
-  ExecuteAuthorizationsParams,
-  ExecuteAuthorizationsResult,
-  GetRequiredAuthorizationsParams,
-  PerpsClientOptions,
-  PlaceOrderParams,
-  RequiredAuthorizationsResult,
+import { projectAccountConfigSettings } from './projectAccountConfigSettings.js'
+import {
+  type CancelOrdersParams,
+  type CheckPrerequisitesParams,
+  type GetAccountResult,
+  type GetSetupParams,
+  type ModifyOrdersParams,
+  type PerpsClientOptions,
+  type PlaceOrderParams,
+  type PlaceTriggerOrderParams,
+  type SatisfySetupParams,
+  type SatisfySetupResult,
+  type SetupResult,
   SigningMode,
+  type WithdrawParams,
 } from './types.js'
 
+const MAX_NONCE_RETRIES = 3
+
 /**
- * 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'
- * })
- * ```
+ * Look up an action's descriptor in the provider's metadata. Throws if the
+ * action isn't declared — defensive: better to fail loudly than to mis-sign.
  */
+function findActionDescriptor(
+  metadata: Provider,
+  action: ActionType
+): ActionDescriptor {
+  const descriptor = [
+    ...metadata.setup,
+    ...metadata.options,
+    ...metadata.actions,
+  ].find((d) => d.type === action)
+  if (!descriptor) {
+    throw new PerpsError(
+      PerpsErrorCode.SDKError,
+      `Provider '${metadata.key}' does not declare action '${action}'.`
+    )
+  }
+  return descriptor
+}
+
 export class PerpsClient {
   private sdkClient: PerpsSDKClient
+  private storage: StorageAdapter
   private signingModes: Map<string, SigningMode> = new Map()
+  private providerMetadataCache: Map<string, Provider> = new Map()
+  private _signer: PerpsSDKClient['signer'] | undefined
+  private readonly lighterConfig: LighterSignerConfig | undefined
+  private readonly lighterReadOnlyTokenOptions:
+    | LighterReadOnlyTokenManagerOptions
+    | undefined
+  private _lighterSigner: LighterSigner | undefined
+  private _lighterKeyStore: LighterKeyStore | undefined
+  private _lighterReadOnlyTokenManager: LighterReadOnlyTokenManager | undefined
 
   constructor(options: PerpsClientOptions) {
+    this.storage = options.storage ?? localStorageAdapter
+    this.lighterConfig = options.lighter
+    this.lighterReadOnlyTokenOptions = options.lighterReadOnlyToken
     this.sdkClient = createPerpsClient({
       integrator: options.integrator,
       apiKey: options.apiKey,
       apiUrl: options.apiUrl,
-      storage: options.storage,
+      storage: this.storage,
+      providers: options.providers,
     })
   }
 
+  private getLighterSigner(): LighterSigner {
+    if (!this._lighterSigner) {
+      this._lighterSigner = new LighterSigner(this.lighterConfig)
+    }
+    return this._lighterSigner
+  }
+
+  private getLighterKeyStore(): LighterKeyStore {
+    if (!this._lighterKeyStore) {
+      this._lighterKeyStore = new LighterKeyStore(this.storage)
+    }
+    return this._lighterKeyStore
+  }
+
+  private getLighterReadOnlyTokenManager(): LighterReadOnlyTokenManager {
+    if (!this._lighterReadOnlyTokenManager) {
+      this._lighterReadOnlyTokenManager = new LighterReadOnlyTokenManager({
+        storage: this.storage,
+        ...this.lighterReadOnlyTokenOptions,
+      })
+    }
+    return this._lighterReadOnlyTokenManager
+  }
+
   /**
-   * Get the underlying SDK client for use with service functions.
+   * Set or update the wallet signer. Used whenever an action's descriptor
+   * names the user wallet in its `signers` list. Pass undefined to clear.
    */
+  setSigner(signer: PerpsSDKClient['signer']): void {
+    this._signer = signer
+    // Override the signer on the sdkClient
+    Object.defineProperty(this.sdkClient, 'signer', {
+      get: () => this._signer,
+      configurable: true,
+    })
+  }
+
   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()}`
+  }
+
+  private signingModeStorageKey(address: Address, provider: string): string {
+    return `lifi-perps-mode:${address.toLowerCase()}:${provider.toLowerCase()}`
+  }
+
+  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)
+    }
+
+    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
   }
 
   /**
-   * 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
+   * Action types that require explicit user input (a chosen mode or tier)
+   * and therefore cannot be bulk-staged through `buildPrerequisites` with
+   * empty params. Callers must dispatch these via `execute(...)` once a
+   * value is picked. The post-`APPROVE_AGENT` auto-upgrade path also
+   * dispatches `ACCOUNT_MODE` directly with `mode: 'unifiedAccount'`.
    */
-  async setSigningMode(
+  private static readonly EXPLICIT_INPUT_PREREQUISITES: ReadonlySet<ActionType> =
+    new Set([ActionType.ACCOUNT_MODE, ActionType.ACCOUNT_TYPE])
+
+  private buildPrerequisiteInputs(
+    prerequisites: ActionDescriptor[],
+    mode: SigningMode,
+    agentAddress?: Address
+  ): Array<{ key: string; params?: Record<string, unknown> }> {
+    return prerequisites
+      .filter((p) => {
+        // ACCOUNT_MODE / ACCOUNT_TYPE require explicit params; they're
+        // dispatched separately via `execute(...)` (or the post-APPROVE_AGENT
+        // auto-upgrade chain) rather than bulk-staged.
+        if (PerpsClient.EXPLICIT_INPUT_PREREQUISITES.has(p.type)) {
+          return false
+        }
+        if (mode === SigningMode.USER) {
+          // USER mode: only items the user can sign, and never APPROVE_AGENT
+          // (no agent is created in this mode).
+          if (!p.signers.includes(PerpsSigner.USER)) {
+            return false
+          }
+          if (p.type === ActionType.APPROVE_AGENT) {
+            return false
+          }
+          return true
+        }
+        // USER_AGENT mode: include every remaining declared prerequisite.
+        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 } : {}),
+        }
+      })
+  }
+
+  private async resolveSignerForAction(
+    action: ActionType,
     address: Address,
-    dex: string,
-    mode: SigningMode
-  ): Promise<void> {
-    const key = this.modeKey(address, dex)
-    this.signingModes.set(key, mode)
+    provider: string
+  ): Promise<Address | undefined> {
+    const mode = await this.loadSigningMode(address, provider)
+    if (mode !== SigningMode.USER_AGENT) {
+      return undefined
+    }
 
-    if (mode === 'USER_AGENT') {
-      // Generate agent keypair if not exists
-      await this.sdkClient.agentManager.getOrCreateAgent(address, dex)
+    // Only AGENT-signed actions surface a distinct signerAddress on the wire.
+    // API_KEY signers (e.g. Lighter's LighterKeyStore) are managed per-provider
+    // and don't have an EVM address — the backend identifies the action by the
+    // L1 `address` instead.
+    const metadata = await this.getProviderMetadata(provider)
+    const allActions = [
+      ...metadata.setup,
+      ...metadata.options,
+      ...metadata.actions,
+    ]
+    const descriptor = allActions.find((d) => d.type === action)
+    if (!descriptor?.signers.includes(PerpsSigner.AGENT)) {
+      return undefined
     }
+
+    const agent = await this.sdkClient.agentManager.getAgent(address, provider)
+    return agent.address
   }
 
   /**
-   * Get the current signing mode for a user + DEX pair.
-   * Defaults to `USER` if not set.
+   * True if any descriptor for the provider lists `PerpsSigner.AGENT`.
+   * Providers like Lighter sign with their own keystore and never need an
+   * AgentManager-managed agent.
    */
-  getSigningMode(address: Address, dex: string): SigningMode {
-    return this.signingModes.get(this.modeKey(address, dex)) ?? 'USER'
+  private async providerUsesAgent(provider: string): Promise<boolean> {
+    const metadata = await this.getProviderMetadata(provider)
+    const all = [...metadata.setup, ...metadata.options, ...metadata.actions]
+    return all.some((d) => d.signers.includes(PerpsSigner.AGENT))
   }
 
-  /**
-   * 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 async autoSignAndExecute(
+    provider: string,
+    address: Address,
+    action: ActionType,
+    actions: ActionStep[],
+    descriptor: ActionDescriptor
+  ): Promise<ExecuteActionResponse> {
+    switch (descriptor.signingMethod) {
+      case SigningMethod.EIP712: {
+        const eip712Actions = actions as Eip712ActionStep[]
+
+        if (descriptor.signers.includes(PerpsSigner.AGENT)) {
+          const agent = await this.sdkClient.agentManager.getAgent(
+            address,
+            provider
+          )
+          const signedActions: SignedActionStep[] = await Promise.all(
+            eip712Actions.map(
+              async (a) =>
+                ({
+                  action: a.action,
+                  typedData: a.typedData,
+                  signature: await signTypedData(agent.privateKey, a.typedData),
+                }) satisfies Eip712SignedActionStep
+            )
+          )
+          return executeAction(this.sdkClient, {
+            provider,
+            address,
+            signerAddress: agent.address,
+            action,
+            actions: signedActions,
+          })
+        }
+
+        if (descriptor.signers.includes(PerpsSigner.USER)) {
+          const signer = this.sdkClient.signer
+          if (!signer) {
+            throw new PerpsError(
+              PerpsErrorCode.SDKError,
+              `Action '${action}' requires a user-wallet signature, but no signer was configured. Pass a WalletClient to createPerpsClient({ signer }).`
+            )
+          }
+          const signedActions: SignedActionStep[] = await Promise.all(
+            eip712Actions.map(
+              async (a) =>
+                ({
+                  action: a.action,
+                  typedData: a.typedData,
+                  signature: await signTypedDataWithSigner(signer, a.typedData),
+                }) satisfies Eip712SignedActionStep
+            )
+          )
+          return executeAction(this.sdkClient, {
+            provider,
+            address,
+            signerAddress: address,
+            action,
+            actions: signedActions,
+          })
+        }
+
+        throw new PerpsError(
+          PerpsErrorCode.SDKError,
+          `Action '${action}' descriptor names no supported signer (signers=[${descriptor.signers.join(', ')}]).`
+        )
+      }
+
+      case SigningMethod.WASM_BLOB: {
+        const wasmActions = actions as WasmBlobActionStep[]
+        const signedActions = await this.signWasmBlobActions(
+          provider,
+          address,
+          wasmActions
+        )
+        return executeAction(this.sdkClient, {
+          provider,
+          address,
+          signerAddress: address,
+          action,
+          actions: signedActions,
+        })
+      }
+
+      case SigningMethod.EVM_TX: {
+        const evmActions = actions as EvmTxActionStep[]
+        const signedActions = await this.signEvmTxActions(evmActions)
+        return executeAction(this.sdkClient, {
+          provider,
+          address,
+          signerAddress: address,
+          action,
+          actions: signedActions,
+        })
+      }
+
+      default:
+        throw new Error(`Unknown signingMethod: ${descriptor.signingMethod}`)
+    }
   }
 
   /**
-   * Check if an agent exists for a user + DEX pair.
+   * Sign a single prerequisite step using whichever signing path matches the
+   * step's shape — EIP-712 typed data, WASM blob (with the hybrid EIP-191 +
+   * WASM flow for REGISTER_API_KEY), or EVM transaction. Lets consumers
+   * collect signed prereqs without embedding per-method signing logic.
    */
-  async hasAgent(address: Address, dex: string): Promise<boolean> {
-    return this.sdkClient.agentManager.hasAgent(address, dex)
+  async signPrerequisite(
+    provider: string,
+    address: Address,
+    step: ActionStep
+  ): Promise<SignedActionStep> {
+    if ('typedData' in step) {
+      if (!this.sdkClient.signer) {
+        throw new PerpsError(
+          PerpsErrorCode.SDKError,
+          'EIP-712 prerequisite signing requires a wallet signer. Pass ' +
+            '`signer` to createPerpsClient or call setSigner(walletClient).'
+        )
+      }
+      return {
+        action: step.action,
+        typedData: step.typedData,
+        signature: await signTypedDataWithSigner(
+          this.sdkClient.signer,
+          step.typedData
+        ),
+      } satisfies Eip712SignedActionStep
+    }
+    if ('wasmSignParams' in step) {
+      const [signed] = await this.signWasmBlobActions(provider, address, [step])
+      return signed
+    }
+    if ('txParams' in step) {
+      const [signed] = await this.signEvmTxActions([step])
+      return signed
+    }
+    throw new PerpsError(
+      PerpsErrorCode.SDKError,
+      'Unknown ActionStep shape — expected typedData, wasmSignParams, or txParams.'
+    )
   }
 
   /**
-   * Remove the agent for a user + DEX pair.
-   * Also resets signing mode to USER.
+   * Sign and broadcast a sequence of EVM transactions via the user's wallet
+   * client. Steps are submitted serially so a later step (e.g. deposit) can
+   * rely on an earlier step (e.g. approve) having mined. Each step's
+   * `txParams` carries chainId, target, function name, args, and a
+   * human-readable abi from the backend.
    */
-  async removeAgent(address: Address, dex: string): Promise<void> {
-    await this.sdkClient.agentManager.removeAgent(address, dex)
-    this.signingModes.delete(this.modeKey(address, dex))
+  private async signEvmTxActions(
+    actions: EvmTxActionStep[]
+  ): Promise<EvmTxSignedActionStep[]> {
+    if (!this.sdkClient.signer) {
+      throw new PerpsError(
+        PerpsErrorCode.SDKError,
+        'EVM_TX signing requires a wallet signer. Pass `signer` to ' +
+          'createPerpsClient or call setSigner(walletClient).'
+      )
+    }
+    const { signer } = this.sdkClient
+    const signed: EvmTxSignedActionStep[] = []
+
+    for (const step of actions) {
+      const params = step.txParams as {
+        chainId: number
+        to: Address
+        functionName: string
+        args: readonly unknown[]
+        abi: readonly string[]
+      }
+
+      const txHash = await signer.writeContract({
+        address: params.to,
+        abi: parseAbi(params.abi),
+        functionName: params.functionName,
+        args: params.args,
+        chain: signer.chain,
+        account: signer.account,
+      })
+
+      signed.push({
+        action: step.action,
+        txParams: step.txParams,
+        txHash,
+      })
+    }
+
+    return signed
   }
 
   /**
-   * Build authorization payloads for signing.
+   * Sign a batch of WASM_BLOB action steps (Lighter). Ensures the user's
+   * Lighter API keypair is registered first — generating one and running the
+   * REGISTER_API_KEY hybrid flow via the L1 signer if not — then feeds each
+   * subsequent step through the WASM signer and returns signed blobs.
    *
-   * 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
+   * `ACCOUNT_TYPE` (Lighter `/api/v1/changeAccountTier`) is dispatched as a
+   * WASM_BLOB envelope by the backend but is NOT a wasm-signed transaction —
+   * Lighter authenticates the endpoint with an auth token and enforces
+   * anti-replay server-side (24h cooldown, no open positions). The signer
+   * mints a Lighter auth token via the same WASM `CreateAuthToken` the read
+   * endpoints use and parks it in `signedTx.txInfo`; the backend's
+   * `executeChangeAccountTier` consumes that field as the `auth` form
+   * parameter. `txType`/`txHash` are unused for this action — they carry
+   * placeholder values to satisfy the `WasmBlobSignedActionStep` shape.
    */
-  async buildAuthorization(
-    params: BuildAuthorizationParams
-  ): Promise<CreateAuthorizationResponse> {
-    const mode = this.getSigningMode(params.address, params.dex)
-    let { signerAddress } = params
+  private async signWasmBlobActions(
+    provider: string,
+    address: Address,
+    actions: WasmBlobActionStep[]
+  ): Promise<WasmBlobSignedActionStep[]> {
+    const signed: WasmBlobSignedActionStep[] = []
+    for (const step of actions) {
+      if (step.action === ActionType.REGISTER_API_KEY) {
+        signed.push(await this.signRegisterApiKey(provider, address, step))
+      } else if (step.action === ActionType.ACCOUNT_TYPE) {
+        signed.push(await this.signAccountTierChange(address, step))
+      } else {
+        signed.push(await this.signStandardWasmAction(provider, address, step))
+      }
+    }
+    return signed
+  }
 
-    if (mode === 'USER_AGENT') {
-      const agent = await this.sdkClient.agentManager.getAgent(
-        params.address,
-        params.dex
+  private async signStandardWasmAction(
+    provider: string,
+    address: Address,
+    step: WasmBlobActionStep
+  ): Promise<WasmBlobSignedActionStep> {
+    const apiKey = await this.getLighterKeyStore().get(address)
+    if (!apiKey) {
+      throw new PerpsError(
+        PerpsErrorCode.SDKError,
+        `No Lighter API key registered for ${address}. ` +
+          'Run prepareAccount / REGISTER_API_KEY first.'
       )
-      signerAddress = signerAddress ?? agent.address
     }
-
-    return createAuthorization(this.sdkClient, {
-      ...params,
-      signerAddress,
+    const signer = this.getLighterSigner()
+    const signedTx = await signer.sign(step.action, step.wasmSignParams, {
+      apiKeyPrivateKey: apiKey.apiKeyPrivateKey,
+      apiKeyIndex: apiKey.apiKeyIndex,
+      accountIndex: apiKey.accountIndex,
     })
+    void provider
+    return {
+      action: step.action,
+      wasmSignParams: step.wasmSignParams,
+      signedTx,
+    }
   }
 
   /**
-   * Submit signed authorizations.
+   * REGISTER_API_KEY flow:
+   *   1. Look up the user's Lighter accountIndex from getAccount()
+   *   2. Generate a fresh Lighter API keypair via the WASM signer
+   *   3. Call SignChangePubKey to produce the WASM blob + EIP-191 message
+   *   4. Have the user's L1 Ethereum wallet sign the message
+   *   5. Inject the L1 signature into the ChangePubKey txInfo JSON
+   *   6. Persist the keypair and return the signed blob
    *
-   * 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
+   * Requires a USER wallet signer to be set via `setSigner` or passed at
+   * construction — the L1 signature is the user's consent to rotate keys.
    */
-  async submitAuthorizations(
-    params: SubmitAuthorizationParams
-  ): Promise<AuthorizationsResponse> {
-    const mode = this.getSigningMode(params.address, params.dex)
-    let { signerAddress } = params
+  private async signRegisterApiKey(
+    provider: string,
+    address: Address,
+    step: WasmBlobActionStep
+  ): Promise<WasmBlobSignedActionStep> {
+    if (!this.sdkClient.signer) {
+      throw new PerpsError(
+        PerpsErrorCode.SDKError,
+        'REGISTER_API_KEY requires a wallet signer — pass `signer` to ' +
+          'createPerpsClient or call setSigner(walletClient).'
+      )
+    }
 
-    if (mode === 'USER_AGENT') {
-      const agent = await this.sdkClient.agentManager.getAgent(
-        params.address,
-        params.dex
+    const params = step.wasmSignParams as {
+      api_key_index?: number
+      nonce?: number
+    }
+    const apiKeyIndex = params.api_key_index ?? DEFAULT_API_KEY_INDEX
+    const nonce = params.nonce
+    if (typeof nonce !== 'number') {
+      throw new PerpsError(
+        PerpsErrorCode.SDKError,
+        'REGISTER_API_KEY wasmSignParams is missing `nonce`.'
+      )
+    }
+
+    const account = await getAccount(this.sdkClient, { provider, address })
+    if (account.config.provider !== 'lighter') {
+      throw new PerpsError(
+        PerpsErrorCode.SDKError,
+        `REGISTER_API_KEY requires a Lighter account, but getAccount ` +
+          `returned config for provider '${account.config.provider}'.`
       )
-      signerAddress = signerAddress ?? agent.address
     }
+    const accountIndex = account.config.accountIndex
+
+    const signer = this.getLighterSigner()
+    const keypair = await signer.generateAPIKey()
+    const changePubKey = await signer.signChangePubKey(
+      keypair.publicKey,
+      keypair.privateKey,
+      nonce,
+      apiKeyIndex,
+      accountIndex
+    )
+
+    const l1Signature = await this.sdkClient.signer.signMessage({
+      account: this.sdkClient.signer.account,
+      message: changePubKey.messageToSign,
+    })
+
+    const txInfoWithL1Sig = signer.embedL1Signature(
+      changePubKey.txInfo,
+      l1Signature
+    )
+
+    const apiKey: LighterApiKey = {
+      accountIndex,
+      apiKeyIndex,
+      apiKeyPrivateKey: keypair.privateKey,
+      apiKeyPublicKey: keypair.publicKey,
+    }
+    await this.getLighterKeyStore().set(address, apiKey)
 
-    return submitAuthorization(this.sdkClient, { ...params, signerAddress })
+    return {
+      action: step.action,
+      wasmSignParams: {
+        ...step.wasmSignParams,
+        new_public_key: keypair.publicKey,
+      },
+      signedTx: {
+        txType: changePubKey.txType,
+        txInfo: txInfoWithL1Sig,
+        txHash: changePubKey.txHash,
+      },
+    }
   }
 
   /**
-   * Build order payloads for signing.
+   * Sign an `ACCOUNT_TYPE` step (Lighter `changeAccountTier`).
    *
-   * In `USER` mode, `signerAddress` is omitted (backend defaults to `address`).
-   * In `USER_AGENT` mode, auto-injects the agent address as `signerAddress`.
+   * Lighter's `/api/v1/changeAccountTier` is an HTTP-only mutation —
+   * Lighter does NOT consume a wasm-signed transaction here; it
+   * authenticates the request with the same auth token its read endpoints
+   * use, and enforces anti-replay business rules server-side. The backend
+   * therefore declares the step as a `WasmBlobActionStep` with
+   * `wasmSignParams.kind = 'changeAccountTier'` and expects the SDK to
+   * mint an auth token in lieu of a transaction signature. That contract
+   * is documented in `lifi-perps-backend/src/providers/lighter/actions/
+   * lighter.actions.accountType.ts` and consumed by `executeChangeAccountTier`.
    *
-   * @param params - Order parameters
-   * @returns Order actions with typed data for signing
+   * The auth-token deadline mirrors {@link createLighterAuthToken}'s 1h
+   * default — Lighter caps tokens at 8h hard, and the backend's executor
+   * runs `verifyPendingAction` then a single `/changeAccountTier` POST,
+   * which completes well inside an hour.
    */
-  async buildOrder(params: PlaceOrderParams): Promise<CreateOrderResponse> {
-    const mode = this.getSigningMode(params.address, params.dex)
-    let signerAddress: Address | undefined
-
-    if (mode === 'USER_AGENT') {
-      const agent = await this.sdkClient.agentManager.getAgent(
-        params.address,
-        params.dex
+  private async signAccountTierChange(
+    address: Address,
+    step: WasmBlobActionStep
+  ): Promise<WasmBlobSignedActionStep> {
+    const apiKey = await this.getLighterKeyStore().get(address)
+    if (!apiKey) {
+      throw new PerpsError(
+        PerpsErrorCode.SDKError,
+        `No Lighter API key registered for ${address}. ` +
+          'Run prepareAccount / REGISTER_API_KEY first.'
       )
-      signerAddress = agent.address
     }
-
-    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,
+    const signer = this.getLighterSigner()
+    const deadline = Math.floor(Date.now() / 1000) + 60 * 60
+    const authToken = await signer.createAuthToken(deadline, {
+      apiKeyPrivateKey: apiKey.apiKeyPrivateKey,
+      apiKeyIndex: apiKey.apiKeyIndex,
+      accountIndex: apiKey.accountIndex,
     })
+    return {
+      action: step.action,
+      wasmSignParams: step.wasmSignParams,
+      signedTx: {
+        // `/changeAccountTier` reads only `txInfo` (the auth token); `txType`
+        // and `txHash` are placeholders to satisfy the envelope shape.
+        txType: 0,
+        txInfo: authToken,
+        txHash: '',
+      },
+    }
   }
 
   /**
-   * Build cancel order payloads for signing.
+   * Return a bearer token that authenticates Lighter's read endpoints
+   * (getOrders, getOrder, getActivity, getFills).
    *
-   * In `USER` mode, `signerAddress` is omitted (backend defaults to `address`).
-   * In `USER_AGENT` mode, auto-injects the agent address as `signerAddress`.
+   * Resolution order:
+   *   1. The long-lived read-only token persisted by `approveReadOnlyToken`,
+   *      when one is stored for this `(address, accountIndex)` AND has not
+   *      passed its recorded `expiry`. The SDK never returns an expired
+   *      stored token.
+   *   2. A freshly minted 8h Lighter auth token, signed off the user's
+   *      Lighter API key. Requires `REGISTER_API_KEY` to have completed.
+   *   3. `undefined` — caller falls back to public reads.
    *
-   * @param params - Cancel parameters
-   * @returns Cancel actions with typed data for signing
+   * `accountIndex` lets callers in pure read-only mode (no API key
+   * registered) target the RO token. When omitted, the SDK derives it from
+   * the user's registered API key.
+   *
+   * `deadlineSeconds` only affects the standard-token fallback (Lighter caps
+   * those tokens at 8h). Read-only tokens carry their own mint-time expiry
+   * recorded by {@link approveReadOnlyToken}.
    */
-  async buildCancelOrder(
-    params: CancelOrdersParams
-  ): Promise<CancelOrderPayloadResponse> {
-    const mode = this.getSigningMode(params.address, params.dex)
-    let signerAddress: Address | undefined
-
-    if (mode === 'USER_AGENT') {
-      const agent = await this.sdkClient.agentManager.getAgent(
-        params.address,
-        params.dex
+  async createLighterAuthToken(
+    address: Address,
+    deadlineSeconds?: number,
+    accountIndex?: number
+  ): Promise<string | undefined> {
+    const apiKey = await this.getLighterKeyStore().get(address)
+    const resolvedAccountIndex = accountIndex ?? apiKey?.accountIndex
+    if (resolvedAccountIndex !== undefined) {
+      const stored = await this.getLighterReadOnlyTokenManager().get(
+        address,
+        resolvedAccountIndex
       )
-      signerAddress = agent.address
+      if (stored) {
+        return stored.token
+      }
     }
-
-    return cancelOrder(this.sdkClient, {
-      dex: params.dex,
-      address: params.address,
-      signerAddress,
-      ids: params.ids,
+    if (!apiKey) {
+      return undefined
+    }
+    const deadline = deadlineSeconds ?? Math.floor(Date.now() / 1000) + 60 * 60
+    const signer = this.getLighterSigner()
+    return signer.createAuthToken(deadline, {
+      apiKeyPrivateKey: apiKey.apiKeyPrivateKey,
+      apiKeyIndex: apiKey.apiKeyIndex,
+      accountIndex: apiKey.accountIndex,
     })
   }
 
   /**
-   * Place an order with automatic agent signing.
+   * Mint a long-lived Lighter read-only token via Lighter's
+   * `tokens/create` endpoint and persist it through the configured
+   * `StorageAdapter`, keyed by `(L1 address, accountIndex)`.
+   *
+   * The user's connected wallet signs an EIP-191 message describing the
+   * mint request; the resulting `Authorization` header authenticates the
+   * Lighter HTTP call. The bearer string Lighter returns is persisted
+   * alongside its `expiry` and `scope`; subsequent calls to
+   * {@link createLighterAuthToken} prefer it over the 8h standard token.
    *
-   * **Requires USER_AGENT mode.** For USER mode, use `buildOrder()` + `submitSignedOrder()`.
+   * `expirySeconds` is the absolute unix-seconds expiry recorded on
+   * Lighter's row. Lighter enforces 1 day ≤ lifetime ≤ 10 years
+   * server-side; the SDK does NOT pre-validate and surfaces Lighter's 400
+   * verbatim. `scope` defaults to `'all'`; the `'single'` variant is wired
+   * through but only useful when the caller has a specific reason to scope
+   * the token to one account.
    *
-   * @param params - Order parameters
-   * @returns Order submission results
-   * @throws {PerpsError} If not in USER_AGENT mode
+   * Requires a USER wallet signer to be set via {@link setSigner} or
+   * passed at construction — the L1 signature is the user's consent.
    */
-  async placeOrder(params: PlaceOrderParams): Promise<SubmitOrderResponse> {
-    const mode = this.getSigningMode(params.address, params.dex)
-
-    if (mode !== 'USER_AGENT') {
+  async approveReadOnlyToken(
+    address: Address,
+    params: ApproveReadOnlyTokenParams
+  ): Promise<ApproveReadOnlyTokenResult> {
+    if (!this.sdkClient.signer) {
       throw new PerpsError(
-        PerpsErrorCode.ValidationError,
-        `${PerpsErrorMessage.InvalidSigningMode} placeOrder() requires USER_AGENT mode. Use createOrder() + submitOrder() for USER mode.`
+        PerpsErrorCode.SDKError,
+        'approveReadOnlyToken requires a wallet signer — pass `signer` to ' +
+          'createPerpsClient or call setSigner(walletClient).'
       )
     }
+    const signer = walletClientSigner(this.sdkClient.signer)
+    return this.getLighterReadOnlyTokenManager().approve(signer, {
+      address,
+      ...params,
+    })
+  }
 
-    const agent = await this.sdkClient.agentManager.getAgent(
-      params.address,
-      params.dex
+  /**
+   * Whether the stored Lighter read-only token for `(address, accountIndex)`
+   * falls within `thresholdDays` of its `expiry`. Returns `false` when no
+   * token is stored, when the stored token has already expired, or when
+   * more than `thresholdDays` of life remain. Intended for widget renewal
+   * banners (default threshold: 30 days).
+   */
+  async isLighterReadOnlyTokenExpiringSoon(
+    address: Address,
+    accountIndex: number,
+    thresholdDays?: number
+  ): Promise<boolean> {
+    return this.getLighterReadOnlyTokenManager().isReadOnlyTokenExpiringSoon(
+      address,
+      accountIndex,
+      thresholdDays
     )
+  }
 
-    // 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,
-    })
+  // ---------------------------------------------------------------------------
+  // Generic action helpers
+  // ---------------------------------------------------------------------------
 
-    // 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),
-      }))
+  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
     )
-
-    // 3. Submit
-    return submitOrder(this.sdkClient, {
-      dex: params.dex,
+    return createAction(this.sdkClient, {
+      provider: params.provider,
       address: params.address,
-      signerAddress: agent.address,
-      actions: signedActions,
+      signerAddress,
+      action,
+      params: params.params,
     })
   }
 
-  /**
-   * 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)
+  // ---------------------------------------------------------------------------
+  // Signing mode management
+  // ---------------------------------------------------------------------------
 
-    if (mode !== 'USER_AGENT') {
-      throw new PerpsError(
-        PerpsErrorCode.ValidationError,
-        `${PerpsErrorMessage.InvalidSigningMode} cancelOrders() requires USER_AGENT mode. Use cancelOrder() + submitOrder() for USER mode.`
-      )
+  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.providerUsesAgent(provider))
+    ) {
+      await this.sdkClient.agentManager.getOrCreateAgent(address, provider)
     }
+  }
 
-    const agent = await this.sdkClient.agentManager.getAgent(
-      params.address,
-      params.dex
+  getSigningMode(address: Address, provider: string): SigningMode {
+    return (
+      this.signingModes.get(this.modeKey(address, provider)) ??
+      SigningMode.USER_AGENT
     )
+  }
 
-    // 1. Create cancel payloads
-    const { actions } = await cancelOrder(this.sdkClient, {
-      dex: params.dex,
-      address: params.address,
-      signerAddress: agent.address,
-      ids: params.ids,
-    })
+  async loadSigningMode(
+    address: Address,
+    provider: string
+  ): Promise<SigningMode> {
+    const key = this.modeKey(address, provider)
+    if (this.signingModes.has(key)) {
+      return this.signingModes.get(key)!
+    }
 
-    // 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),
-      }))
+    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
+  }
 
-    // 3. Submit
-    return submitOrder(this.sdkClient, {
-      dex: params.dex,
-      address: params.address,
-      signerAddress: agent.address,
-      actions: signedActions,
-    })
+  async loadAgentMode(address: Address, provider: string): Promise<boolean> {
+    const mode = await this.loadSigningMode(address, provider)
+    return mode === SigningMode.USER_AGENT
   }
 
-  /**
-   * 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)
+  async setAgentMode(
+    address: Address,
+    provider: string,
+    useAgent: boolean
+  ): Promise<void> {
+    await this.setSigningMode(
+      address,
+      provider,
+      useAgent ? SigningMode.USER_AGENT : SigningMode.USER
+    )
+  }
+
+  async getAgentAddress(address: Address, provider: string): Promise<Address> {
+    const agent = await this.sdkClient.agentManager.getAgent(address, provider)
+    return agent.address
+  }
+
+  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))
   }
 
+  // ---------------------------------------------------------------------------
+  // Account
+  // ---------------------------------------------------------------------------
+
   /**
-   * 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
+   * Fetch the user's account state from the backend and attach the
+   * SDK-projected `settings` array — one `AccountConfigSetting` per
+   * descriptor on `Provider.setup` + `Provider.options`. Callers read
+   * `result.settings` directly without re-deriving values from the typed
+   * `AccountConfig`.
    */
-  async buildWithdrawal(
-    params: BuildWithdrawalParams
-  ): Promise<CreateWithdrawalResponse> {
-    return createWithdrawal(this.sdkClient, {
-      dex: params.dex,
-      address: params.address,
-      withdrawal: params.withdrawal,
-    })
+  async getAccount(params: {
+    provider: string
+    address: Address
+  }): Promise<GetAccountResult> {
+    const [response, metadata] = await Promise.all([
+      getAccount(this.sdkClient, params),
+      this.getProviderMetadata(params.provider),
+    ])
+    const settings = projectAccountConfigSettings(
+      response.config,
+      metadata.setup,
+      metadata.options
+    )
+    return { ...response, settings }
   }
 
   /**
-   * Submit a signed withdrawal.
-   *
-   * Withdrawals are user-signed only — agents cannot initiate withdrawals.
-   *
-   * @param params - Signed withdrawal parameters
-   * @returns Withdrawal result
+   * Thin existence check for a provider account at `address`. Returns
+   * `true` when `getAccount` resolves, `false` when the backend reports
+   * `PerpsErrorCode.AccountNotFound`, and re-throws on any other error
+   * (transport failures, validation errors, server errors).
    */
-  async submitWithdrawal(
-    params: SubmitWithdrawalParams
-  ): Promise<SubmitWithdrawalResponse> {
-    return submitWithdrawal(this.sdkClient, params)
+  async accountExists(provider: string, address: Address): Promise<boolean> {
+    try {
+      await getAccount(this.sdkClient, { provider, address })
+      return true
+    } catch (err) {
+      if (
+        err instanceof PerpsError &&
+        err.code === PerpsErrorCode.AccountNotFound
+      ) {
+        return false
+      }
+      throw err
+    }
   }
 
+  // ---------------------------------------------------------------------------
+  // Setup
+  // ---------------------------------------------------------------------------
+
   /**
-   * 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.
+   * Return the unsatisfied entries on `Provider.setup` for this account,
+   * split by signer role. Trading is gated on `isReady === true`.
    *
-   * @param params - Parameters including dex, address, and dex-specific config
-   * @returns Which authorizations are needed and whether the user is ready to trade
+   * `Provider.options` descriptors are NEVER returned here — options are
+   * post-setup tunables and never gate trading. Option state is surfaced
+   * separately via `getAccount().settings`.
    */
-  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
+  async checkSetup(params: GetSetupParams): Promise<SetupResult> {
+    const { provider, address } = params
+    const mode = await this.loadSigningMode(address, provider)
+
+    const metadata = await this.getProviderMetadata(provider)
+    const usesAgent = [
+      ...metadata.setup,
+      ...metadata.options,
+      ...metadata.actions,
+    ].some((d) => d.signers.includes(PerpsSigner.AGENT))
+
     let agentAddress: Address | undefined
-    if (mode === 'USER_AGENT') {
+    if (mode === SigningMode.USER_AGENT && usesAgent) {
       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 allInputs = this.buildPrerequisiteInputs(
+      metadata.setup,
+      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 setup descriptors.
+    const signersByAction = new Map<string, PerpsSigner[]>()
+    for (const desc of metadata.setup) {
+      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,
     }
   }
 
+  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.setup,
+      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 }
+  }
+
+  /**
+   * Default mode the SDK auto-applies after `APPROVE_AGENT` on a provider
+   * whose `options` array exposes a writable `ACCOUNT_MODE` (today
+   * Hyperliquid). Callers can override this through a subsequent
+   * `ACCOUNT_MODE` dispatch.
+   */
+  private static readonly DEFAULT_ACCOUNT_MODE = 'unifiedAccount'
+
   /**
-   * Execute authorizations: submit user-signed actions, then auto-sign and submit
-   * any agent authorizations.
+   * Prepare an `ACCOUNT_MODE` change by proactively reading the account's
+   * current `config.abstractionMode` and routing to the correct signer:
    *
-   * @param params - User-signed actions and the required authorizations result
-   * @returns Combined results from user and agent submissions
+   * - `abstractionMode == null` (never set, e.g. a fresh HL account):
+   *   the change MAY be performed by the agent signer. Build, sign with
+   *   the agent key, and dispatch. Returns `{ results }`.
+   * - `abstractionMode === mode`: idempotent no-op. Returns an empty
+   *   results envelope without contacting `/createAction` or `/executeAction`.
+   * - `abstractionMode` set to any other value: HL requires a user-wallet
+   *   signature to change the abstraction once it has been set. Build the
+   *   action unsigned and return it as `{ fallback }` so the caller can
+   *   surface a wallet prompt via `fallbackUserPrerequisites`.
+   *
+   * Network errors from `/account` propagate — we never guess the signer.
+   * `account.config.provider !== 'hyperliquid'` also throws: this helper
+   * is HL-specific and the dispatcher should never reach it for another
+   * provider (gated by `hasWritableAccountMode`).
    */
-  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: [] }
+  private async prepareAccountModeChange(
+    provider: string,
+    address: Address,
+    mode: string
+  ): Promise<{
+    results?: ExecuteActionResponse
+    fallback?: ActionStep[]
+  }> {
+    const account = await getAccount(this.sdkClient, { provider, address })
+    if (account.config.provider !== 'hyperliquid') {
+      throw new PerpsError(
+        PerpsErrorCode.SDKError,
+        `prepareAccountModeChange is Hyperliquid-specific, but ` +
+          `getAccount returned config for provider ` +
+          `'${account.config.provider}'.`
+      )
+    }
+    const currentStatus = account.config.abstractionMode
+
+    // Idempotent short-circuit: already in the requested mode.
+    if (currentStatus === mode) {
+      return {}
+    }
+
+    // Never set → the agent is authorised to perform the change.
+    if (currentStatus == null) {
+      const agent = await this.sdkClient.agentManager.getAgent(
+        address,
+        provider
+      )
+
+      const { actions } = await createAction(this.sdkClient, {
+        provider,
+        address,
+        signerAddress: agent.address,
+        action: ActionType.ACCOUNT_MODE,
+        params: { mode } satisfies ActionParamsMap[ActionType.ACCOUNT_MODE],
+      })
+
+      if (actions.length === 0) {
+        // Backend's per-mode early-exit (defensive — shouldn't fire given
+        // the short-circuit above, but covers a race between our /account
+        // read and the backend's view of the current status).
+        return { results: { results: [] } }
+      }
+
+      const signedActions: SignedActionStep[] = await Promise.all(
+        (actions as Eip712ActionStep[]).map(
+          async (a): Promise<Eip712SignedActionStep> => ({
+            action: a.action,
+            typedData: a.typedData,
+            signature: await signTypedData(agent.privateKey, a.typedData),
+          })
+        )
+      )
+
+      const results = await executeAction(this.sdkClient, {
+        provider,
+        address,
+        signerAddress: agent.address,
+        action: ActionType.ACCOUNT_MODE,
+        actions: signedActions,
+      })
+
+      return { results }
+    }
+
+    // Already set to a different mode → HL requires a user-wallet signature.
+    // Build the action unsigned and surface it as a fallback to the caller.
+    const { actions: fallbackActions } = await createAction(this.sdkClient, {
+      provider,
+      address,
+      action: ActionType.ACCOUNT_MODE,
+      params: { mode } satisfies ActionParamsMap[ActionType.ACCOUNT_MODE],
+    })
+
+    return {
+      fallback: fallbackActions.length > 0 ? fallbackActions : undefined,
+    }
+  }
+
+  /**
+   * True when the provider exposes an `ACCOUNT_MODE` descriptor (in `setup`
+   * or `options`) whose `mode` Param has a writable enumeration of values.
+   * Providers that omit `ACCOUNT_MODE` or expose it as read-only / free-form
+   * input return false.
+   */
+  private static hasWritableAccountMode(metadata: Provider): boolean {
+    const item = [...metadata.setup, ...metadata.options].find(
+      (i) => i.type === ActionType.ACCOUNT_MODE
+    )
+    if (!item) {
+      return false
+    }
+    const modeParam = item.params.find((p) => p.name === 'mode')
+    if (!modeParam) {
+      return false
+    }
+    // Writable multi-option: `values` enumerates choices and `readOnly`
+    // is not set (treat absence as writable, matching the descriptor
+    // contract in `Param`).
+    if (!modeParam.values || modeParam.values.length === 0) {
+      return false
+    }
+    return !modeParam.readOnly
+  }
+
+  /**
+   * Submit the signed setup steps returned by `checkSetup` (and seeded
+   * with user-wallet signatures by the caller). Internally splits into:
+   *
+   *   1. Submit user-signed setup actions.
+   *   2. After a successful `APPROVE_AGENT`, auto-upgrade `ACCOUNT_MODE`
+   *      to the SDK's default when the provider exposes a writable
+   *      `ACCOUNT_MODE` Param (Hyperliquid today). The SDK reads
+   *      `account.config.abstractionMode` to choose the signer: `null` →
+   *      agent dispatch; non-null → wallet fallback returned in
+   *      `fallbackUserPrerequisites`.
+   *   3. Sign and submit any pre-staged agent-side setup actions the
+   *      backend returned alongside the user-signed ones.
+   */
+  async satisfySetup(params: SatisfySetupParams): Promise<SatisfySetupResult> {
+    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-upgrade ACCOUNT_MODE after APPROVE_AGENT.
+    //
+    // When the user-signed setup included a successful APPROVE_AGENT, the
+    // freshly approved agent is now authorised to sign account-level
+    // actions for accounts whose abstraction has never been set. If the
+    // provider exposes a writable `ACCOUNT_MODE` descriptor (Hyperliquid
+    // today), the SDK reads `account.config.abstractionMode` to decide
+    // the signer: `null` → agent-dispatch silently to the SDK's preferred
+    // default; non-null → return a wallet-signing fallback step. Either
+    // way the chain does NOT abort onboarding — `ACCOUNT_MODE` lives on
+    // `Provider.options`, not `Provider.setup`, and so does not gate
+    // trading.
+    let agentResults: ExecuteActionResponse | undefined
+    let fallbackUserPrerequisites: ActionStep[] | undefined
+    if (mode === SigningMode.USER_AGENT) {
+      const justApprovedAgent = userResults.results.some(
+        (r) => r.success && r.action === ActionType.APPROVE_AGENT
+      )
+      if (justApprovedAgent) {
+        const metadata = await this.getProviderMetadata(provider)
+        if (PerpsClient.hasWritableAccountMode(metadata)) {
+          const upgrade = await this.prepareAccountModeChange(
+            provider,
+            address,
+            PerpsClient.DEFAULT_ACCOUNT_MODE
+          )
+          agentResults = upgrade.results
+          fallbackUserPrerequisites = upgrade.fallback
+        }
+      }
+    }
+
+    // 3. Sign and submit any pre-staged agent prerequisites returned by the
+    //    backend's `buildPrerequisites` call. ACCOUNT_MODE is filtered out of
+    //    bulk staging (it requires explicit `mode` params), so this block
+    //    today only runs for future agent-signed steps the backend chooses
+    //    to stage.
+    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) => ({
-          action: action.action,
-          typedData: action.typedData,
-          signature: await signTypedData(agent.privateKey, action.typedData),
-        }))
+      const signedAgentActions: SignedActionStep[] = await Promise.all(
+        (required.agentPrerequisites as Eip712ActionStep[]).map(
+          async (action) =>
+            ({
+              action: action.action,
+              typedData: action.typedData,
+              signature: await signTypedData(
+                agent.privateKey,
+                action.typedData
+              ),
+            }) satisfies Eip712SignedActionStep
+        )
       )
 
-      const agentResults = await submitAuthorization(this.sdkClient, {
-        dex,
+      const firstAction = required.agentPrerequisites[0]?.action as string
+      const stagedResults = await executeAction(this.sdkClient, {
+        provider,
         address,
         signerAddress: agent.address,
+        action: (firstAction ?? ActionType.ACCOUNT_MODE) as ActionType,
         actions: signedAgentActions,
       })
 
-      return { userResults, agentResults }
+      // Merge staged-prereq results with any auto-upgrade results from step 2.
+      agentResults = {
+        results: [...(agentResults?.results ?? []), ...stagedResults.results],
+      }
+    }
+
+    return {
+      userResults,
+      ...(agentResults ? { agentResults } : {}),
+      ...(fallbackUserPrerequisites ? { fallbackUserPrerequisites } : {}),
     }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Typed action helpers
+  // ---------------------------------------------------------------------------
+
+  async placeOrder(params: PlaceOrderParams): Promise<ExecuteActionResponse> {
+    return this.execute({ ...params, action: ActionType.PLACE_ORDER, params })
+  }
+
+  async placeTriggerOrder(
+    params: PlaceTriggerOrderParams
+  ): Promise<ExecuteActionResponse> {
+    return this.execute({
+      ...params,
+      action: ActionType.PLACE_TRIGGER_ORDER,
+      params,
+    })
+  }
 
-    return { userResults }
+  async cancelOrders(
+    params: CancelOrdersParams
+  ): Promise<ExecuteActionResponse> {
+    return this.execute({ ...params, action: ActionType.CANCEL_ORDER, params })
+  }
+
+  async modifyOrders(
+    params: ModifyOrdersParams
+  ): Promise<ExecuteActionResponse> {
+    return this.execute({ ...params, action: ActionType.MODIFY_ORDER, params })
+  }
+
+  async updatePositionMargin(params: {
+    provider: string
+    address: Address
+    asset: AssetIdentity
+    action: 'add' | 'remove'
+    amount: string
+  }): Promise<ExecuteActionResponse> {
+    return this.execute({
+      ...params,
+      action: ActionType.UPDATE_POSITION_MARGIN,
+      params,
+    })
+  }
+
+  async withdraw(params: WithdrawParams): Promise<ExecuteActionResponse> {
+    return this.execute({
+      provider: params.provider,
+      address: params.address,
+      action: ActionType.WITHDRAWAL,
+      params: params.withdrawal,
+    })
+  }
+
+  /**
+   * Execute any action through the SDK's signing pipeline. Signing is routed
+   * by the action's descriptor in provider metadata — the agent keypair, the
+   * configured WalletClient signer, the Lighter API key, or an EVM tx — as
+   * the descriptor's `signers` and `signingMethod` dictate.
+   */
+  async execute<T extends ActionType>(params: {
+    provider: string
+    address: Address
+    signerAddress?: Address
+    action: T
+    params: ActionParamsMap[T]
+  }): Promise<ExecuteActionResponse> {
+    await this.loadSigningMode(params.address, params.provider)
+    const metadata = await this.getProviderMetadata(params.provider)
+    const descriptor = findActionDescriptor(metadata, params.action)
+
+    let lastError: unknown
+    for (let attempt = 0; attempt < MAX_NONCE_RETRIES; attempt++) {
+      const { actions } = await this.buildAction(params.action, {
+        provider: params.provider,
+        address: params.address,
+        params: params.params,
+      })
+      try {
+        return await this.autoSignAndExecute(
+          params.provider,
+          params.address,
+          params.action,
+          actions,
+          descriptor
+        )
+      } catch (err) {
+        if (
+          err instanceof PerpsError &&
+          err.code === PerpsErrorCode.InvalidNonce
+        ) {
+          lastError = err
+          continue
+        }
+        throw err
+      }
+    }
+    throw lastError
   }
 }