@lifi/perps-sdk 0.1.1-alpha.9 → 1.0.0

package/dist/esm/client/PerpsClient.js

@@ -1,438 +1,498 @@
-import { PerpsErrorCode } from '@lifi/perps-types';
-import { getDexAuthProvider } from '../dex/registry.js';
-import { PerpsErrorMessage } from '../errors/constants.js';
+import { ActionType, PerpsErrorCode } from '@lifi/perps-types';
 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 { submitAuthorization } from '../services/submitAuthorization.js';
-import { submitOrder } from '../services/submitOrder.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 as fetchAccount } from '../services/getAccount.js';
+import { getProviders } from '../services/getProviders.js';
 import { createPerpsClient } from './createPerpsClient.js';
+import { requireProvider as resolveProvider } from './requireProvider.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 ...
+ * 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, action) {
+    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;
+}
+/**
+ * The primary high-level perps API: wraps a {@link PerpsSDKClient} and owns the
+ * end-to-end signing pipeline for provider setup, orders, and account-level
+ * actions. Construct via `new PerpsClient(options)` or the SDK's higher-level
+ * wiring.
  *
- * // 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'
- * })
- * ```
+ * @public
  */
 export class PerpsClient {
     sdkClient;
-    signingModes = new Map();
+    providerMetadataCache = new Map();
+    _userWallet;
     constructor(options) {
         this.sdkClient = createPerpsClient({
             integrator: options.integrator,
             apiKey: options.apiKey,
             apiUrl: options.apiUrl,
-            storage: options.storage,
+            providers: options.providers,
         });
     }
     /**
-     * Get the underlying SDK client for use with service functions.
-     */
-    get client() {
-        return this.sdkClient;
-    }
-    /**
-     * Get the storage key for a user + DEX pair.
+     * Set or update the end-user's wallet. Used whenever an action's descriptor
+     * names the user wallet in its `signers` list. Pass undefined to clear.
+     *
+     * @public
      */
-    modeKey(address, dex) {
-        return `${address.toLowerCase()}:${dex.toLowerCase()}`;
+    setUserWallet(userWallet) {
+        this._userWallet = userWallet;
+        Object.defineProperty(this.sdkClient, 'userWallet', {
+            get: () => this._userWallet,
+            configurable: true,
+        });
     }
     /**
-     * Set the signing mode for a user + DEX pair.
+     * The underlying low-level {@link PerpsSDKClient} (config, user wallet,
+     * provider registry) backing this instance.
      *
-     * 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
+     * @public
      */
-    async setSigningMode(address, dex, mode) {
-        const key = this.modeKey(address, dex);
-        this.signingModes.set(key, mode);
-        if (mode === 'USER_AGENT') {
-            // Generate agent keypair if not exists
-            await this.sdkClient.agentManager.getOrCreateAgent(address, dex);
+    get client() {
+        return this.sdkClient;
+    }
+    async getProviderMetadata(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;
     }
     /**
-     * Get the current signing mode for a user + DEX pair.
-     * Defaults to `USER` if not set.
+     * Resolve the registered provider plugin for `provider`, throwing a
+     * `PerpsError` when the caller has not registered one via the SDK's
+     * `providers` option. The plugin owns signer identity and write-side signing.
      */
-    getSigningMode(address, dex) {
-        return this.signingModes.get(this.modeKey(address, dex)) ?? 'USER';
+    requireProvider(provider) {
+        return resolveProvider(this.sdkClient, provider);
     }
     /**
-     * Get the agent address for a user + DEX pair.
-     *
-     * @throws {PerpsError} If in USER mode or agent not found
+     * Ask the provider plugin for the signer-bearing wire fields of `action` —
+     * the on-wire `signerAddress` and any signer-derived params (e.g.
+     * Hyperliquid's `agentAddress` for `APPROVE_AGENT`). Forwards the descriptor's
+     * `signers` so the plugin can branch on signer role. Returns empty when the
+     * plugin signs as the user or with a non-EVM credential. Core constructs no
+     * `signerAddress` itself; signer identity is plugin-owned.
      */
-    async getAgentAddress(address, dex) {
-        const agent = await this.sdkClient.agentManager.getAgent(address, dex);
-        return agent.address;
+    async resolveActionRequest(provider, descriptor, address) {
+        const plugin = this.requireProvider(provider);
+        if (typeof plugin.resolveActionRequest !== 'function') {
+            return {};
+        }
+        return plugin.resolveActionRequest(descriptor.type, address, descriptor.signers);
     }
     /**
-     * Check if an agent exists for a user + DEX pair.
+     * Delegate signing of `actions` to the provider plugin. The plugin owns
+     * every signing arm and branches on the descriptor's `signers` internally,
+     * reading the end-user's wallet from the {@link SignActionsContext} when an
+     * arm signs as the user.
      */
-    async hasAgent(address, dex) {
-        return this.sdkClient.agentManager.hasAgent(address, dex);
+    async delegateSignActions(provider, address, descriptor, actions) {
+        const plugin = this.requireProvider(provider);
+        if (typeof plugin.signActions !== 'function') {
+            throw new PerpsError(PerpsErrorCode.SDKError, `Provider '${provider}' does not implement signActions for ` +
+                `signingMethod '${descriptor.signingMethod}'.`);
+        }
+        return plugin.signActions(descriptor.signingMethod, actions, address, this.buildSignActionsContext(descriptor));
     }
     /**
-     * Remove the agent for a user + DEX pair.
-     * Also resets signing mode to USER.
+     * Assemble the per-call context the provider plugin needs in order to sign:
+     * the end-user's wallet and the descriptor's declared `signers`. Core
+     * forwards `signers` as data so the plugin can pick WHO signs; it does not
+     * branch on them. Provider-owned session credentials (the Hyperliquid agent
+     * keypair, Lighter's API key) are resolved inside the provider's
+     * `signActions`, not threaded through here.
      */
-    async removeAgent(address, dex) {
-        await this.sdkClient.agentManager.removeAgent(address, dex);
-        this.signingModes.delete(this.modeKey(address, dex));
+    buildSignActionsContext(descriptor) {
+        const ctx = { signers: descriptor.signers };
+        if (this.sdkClient.userWallet !== undefined) {
+            ctx.userWallet = this.sdkClient.userWallet;
+        }
+        return ctx;
     }
     /**
-     * Build authorization payloads for signing.
+     * Sign a single provider setup action step by delegating to the provider
+     * plugin, which branches on the step's signing scheme internally. Lets
+     * consumers collect signed setup actions without embedding per-method
+     * signing logic.
      *
-     * In `USER` mode, `signerAddress` is omitted (backend defaults to `address`).
-     * In `USER_AGENT` mode, auto-injects the agent address as `signerAddress`.
+     * @throws {PerpsError} When the step's action is not declared by the provider.
+     * @public
+     */
+    async signProviderSetupAction(provider, address, step) {
+        const metadata = await this.getProviderMetadata(provider);
+        const descriptor = findActionDescriptor(metadata, step.action);
+        const [signed] = await this.delegateSignActions(provider, address, descriptor, [step]);
+        return signed;
+    }
+    /**
+     * Build (but do not sign or submit) the unsigned action steps for `action`,
+     * letting the provider plugin contribute any signer-bearing request fields.
      *
-     * @param params - Authorization parameters
-     * @returns Authorization actions with typed data for signing
+     * @public
      */
-    async buildAuthorization(params) {
-        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);
-            signerAddress = signerAddress ?? agent.address;
-        }
-        return createAuthorization(this.sdkClient, {
-            ...params,
+    async buildAction(action, params) {
+        const metadata = await this.getProviderMetadata(params.provider);
+        const descriptor = findActionDescriptor(metadata, action);
+        const { signerAddress, params: signerParams } = await this.resolveActionRequest(params.provider, descriptor, params.address);
+        return createAction(this.sdkClient, {
+            provider: params.provider,
+            address: params.address,
             signerAddress,
+            action,
+            params: {
+                ...params.params,
+                ...signerParams,
+            },
         });
     }
     /**
-     * Submit signed authorizations.
+     * 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`.
      *
-     * In `USER` mode, `signerAddress` is omitted (backend defaults to `address`).
-     * In `USER_AGENT` mode, auto-injects the agent address as `signerAddress`.
+     * @throws {PerpsError} When the provider plugin is not registered, or the
+     *   backend account fetch fails.
+     * @public
+     */
+    async getAccount(params) {
+        const plugin = this.requireProvider(params.provider);
+        const [response, metadata] = await Promise.all([
+            fetchAccount(this.sdkClient, params),
+            this.getProviderMetadata(params.provider),
+        ]);
+        const settings = plugin.projectConfig(response.config, metadata.setup, metadata.options);
+        return { ...response, settings };
+    }
+    /**
+     * Roll an already-fetched {@link AccountResponse} (plus its positions) up
+     * into an {@link AccountSummary}, delegating to the owning provider so the
+     * venue-specific collateral and margin semantics are applied correctly.
+     */
+    getAccountSummary(account, positions) {
+        return this.requireProvider(account.provider).getAccountSummary(account, positions);
+    }
+    /**
+     * 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).
      *
-     * @param params - Signed authorization parameters
+     * @throws {PerpsError} On any backend error other than
+     *   `PerpsErrorCode.AccountNotFound`.
+     * @public
      */
-    async submitAuthorizations(params) {
-        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);
-            signerAddress = signerAddress ?? agent.address;
+    async accountExists(provider, address) {
+        try {
+            await fetchAccount(this.sdkClient, { provider, address });
+            return true;
+        }
+        catch (err) {
+            if (err instanceof PerpsError &&
+                err.code === PerpsErrorCode.AccountNotFound) {
+                return false;
+            }
+            throw err;
         }
-        return submitAuthorization(this.sdkClient, { ...params, signerAddress });
     }
     /**
-     * Build order payloads for signing.
+     * Return the unsatisfied entries on `Provider.setup` for this account as a
+     * flat, self-describing list. Trading is gated on `isReady === true`.
      *
-     * In `USER` mode, `signerAddress` is omitted (backend defaults to `address`).
-     * In `USER_AGENT` mode, auto-injects the agent address as `signerAddress`.
+     * `Provider.options` descriptors are NEVER returned here — options are
+     * post-setup tunables and never gate trading. Option state is surfaced
+     * separately via `getAccount().settings`.
      *
-     * @param params - Order parameters
-     * @returns Order actions with typed data for signing
+     * @public
      */
-    async buildOrder(params) {
-        const mode = this.getSigningMode(params.address, params.dex);
-        let signerAddress;
-        if (mode === 'USER_AGENT') {
-            const agent = await this.sdkClient.agentManager.getAgent(params.address, params.dex);
-            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,
-        });
+    async checkSetup(params) {
+        const { provider, address } = params;
+        // The backend filters already-satisfied setup actions and returns typed
+        // data for those still outstanding; each plugin contributes its own
+        // signer-bearing request fields.
+        const { actions } = await this.buildProviderSetup({ provider, address });
+        return {
+            setup: actions,
+            isReady: actions.length === 0,
+        };
     }
     /**
-     * Build cancel order payloads for signing.
+     * Build the unsigned setup `ActionStep`s still outstanding for an account,
+     * ordered by descriptor `sequence`. The backend filters already-satisfied
+     * setup; each plugin contributes its own signer-bearing request fields and
+     * any local-state params (e.g. Lighter's known pubkey).
      *
-     * 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
+     * @public
      */
-    async buildCancelOrder(params) {
-        const mode = this.getSigningMode(params.address, params.dex);
-        let signerAddress;
-        if (mode === 'USER_AGENT') {
-            const agent = await this.sdkClient.agentManager.getAgent(params.address, params.dex);
-            signerAddress = agent.address;
+    async buildProviderSetup(params) {
+        const { provider, address } = params;
+        const metadata = await this.getProviderMetadata(provider);
+        const orderedSetup = [...metadata.setup].sort((a, b) => (a.sequence ?? Number.MAX_SAFE_INTEGER) -
+            (b.sequence ?? Number.MAX_SAFE_INTEGER));
+        const plugin = this.sdkClient.getProvider(provider);
+        const allActions = [];
+        for (const descriptor of orderedSetup) {
+            const action = descriptor.type;
+            const { signerAddress, params: signerParams } = await this.resolveActionRequest(provider, descriptor, address);
+            const localParams = plugin?.resolveSetupParams
+                ? await plugin.resolveSetupParams(action, address)
+                : {};
+            const { actions } = await createAction(this.sdkClient, {
+                provider,
+                address,
+                signerAddress,
+                action,
+                params: {
+                    ...signerParams,
+                    ...localParams,
+                },
+            });
+            allActions.push(...actions);
         }
-        return cancelOrder(this.sdkClient, {
-            dex: params.dex,
-            address: params.address,
-            signerAddress,
-            ids: params.ids,
-        });
+        return { actions: allActions };
     }
     /**
-     * Place an order with automatic agent signing.
-     *
-     * **Requires USER_AGENT mode.** For USER mode, use `buildOrder()` + `submitSignedOrder()`.
+     * Submit the signed setup steps returned by `checkSetup` (and signed by the
+     * caller / `signProviderSetupAction`). Routes the batch on the first step's
+     * action and lets the plugin contribute that action's `signerAddress`.
+     * Throws on any per-step venue rejection.
      *
-     * @param params - Order parameters
-     * @returns Order submission results
-     * @throws {PerpsError} If not in USER_AGENT mode
+     * @public
      */
-    async placeOrder(params) {
-        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 executeProviderSetup(params) {
+        const { provider, address, setup, signedActions } = params;
+        if (signedActions.length === 0) {
+            return { results: { results: [] } };
         }
-        const agent = await this.sdkClient.agentManager.getAgent(params.address, params.dex);
-        // 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,
-        });
-        // 2. Sign each action with agent key
-        const signedActions = await Promise.all(actions.map(async (a) => ({
-            action: a.action,
-            typedData: a.typedData,
-            signature: await signTypedData(agent.privateKey, a.typedData),
-        })));
-        // 3. Submit
-        return submitOrder(this.sdkClient, {
-            dex: params.dex,
-            address: params.address,
-            signerAddress: agent.address,
+        const action = setup[0]?.action ?? signedActions[0].action;
+        const metadata = await this.getProviderMetadata(provider);
+        const descriptor = findActionDescriptor(metadata, action);
+        const { signerAddress } = await this.resolveActionRequest(provider, descriptor, address);
+        const results = await executeAction(this.sdkClient, {
+            provider,
+            address,
+            // The submitting account: the plugin-resolved signer (Hyperliquid's
+            // agent) when present, else the end-user's address.
+            signerAddress: signerAddress ?? address,
+            action,
             actions: signedActions,
         });
+        const failure = results.results.find((r) => !r.success);
+        if (failure) {
+            throw new PerpsError(PerpsErrorCode.ExchangeRejected, failure.error);
+        }
+        return { results };
     }
     /**
-     * Cancel orders with automatic agent signing.
+     * Sign and submit one pre-staged setup `ActionStep` end-to-end.
      *
-     * **Requires USER_AGENT mode.** For USER mode, use `buildCancelOrder()` + `submitSignedOrder()`.
+     * The caller is expected to have already obtained the step from a prior
+     * {@link checkSetup} call (typically cached by the widget's react-query) —
+     * we do NOT refetch. This avoids the double `createAction` round-trip and
+     * keeps the nonce that was allocated at staging time committed all the way
+     * through submit. If the cached step has gone stale (Lighter's `/nextNonce`
+     * advanced underneath us), `executeProviderSetup` will surface a nonce
+     * conflict that the caller invalidates on, refetches `checkSetup`, and
+     * retries with a fresh step.
      *
-     * @param params - Cancel parameters
-     * @returns Cancel submission results
-     * @throws {PerpsError} If not in USER_AGENT mode
+     * @throws {PerpsError} When the step's action is not in the provider's
+     *   `setup` descriptors.
+     * @public
      */
-    async cancelOrders(params) {
-        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 executeProviderSetupAction(params) {
+        const { provider, address, step } = params;
+        const metadata = await this.getProviderMetadata(provider);
+        const descriptor = metadata.setup.find((d) => d.type === step.action);
+        if (!descriptor) {
+            throw new PerpsError(PerpsErrorCode.SDKError, `Action '${step.action}' is not in '${provider}'.setup`);
         }
-        const agent = await this.sdkClient.agentManager.getAgent(params.address, params.dex);
-        // 1. Create cancel payloads
-        const { actions } = await cancelOrder(this.sdkClient, {
-            dex: params.dex,
-            address: params.address,
-            signerAddress: agent.address,
-            ids: params.ids,
-        });
-        // 2. Sign each action with agent key
-        const signedActions = await Promise.all(actions.map(async (a) => ({
-            action: a.action,
-            typedData: a.typedData,
-            signature: await signTypedData(agent.privateKey, a.typedData),
-        })));
-        // 3. Submit
-        return submitOrder(this.sdkClient, {
-            dex: params.dex,
-            address: params.address,
-            signerAddress: agent.address,
-            actions: signedActions,
+        const signed = await this.signProviderSetupAction(provider, address, step);
+        await this.executeProviderSetup({
+            provider,
+            address,
+            setup: [step],
+            signedActions: [signed],
         });
     }
     /**
-     * Submit pre-signed order actions.
+     * Sign and submit a single provider-option change (a `Provider.options`
+     * tunable such as Lighter `ACCOUNT_TYPE` or Hyperliquid `ACCOUNT_MODE`)
+     * end-to-end, throwing on a venue rejection.
      *
-     * 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`).
+     * Options are dispatched through the same {@link execute} pipeline as
+     * trades, but unlike a trade an option change is a single mandatory action:
+     * a per-action `success: false` (returned as a 200 OK) means the user's
+     * selection was rejected and must surface, not be silently dropped. This
+     * wrapper inspects the result and throws a {@link PerpsError} carrying the
+     * venue `error`, giving options the same throw contract that setup has via
+     * {@link executeProviderSetupAction}. The only structural difference is that
+     * an option carries `params` (the selected value) rather than a pre-staged
+     * step.
      *
-     * @param params - Signed order parameters
+     * `execute` itself is unchanged — it still returns results without throwing,
+     * which the trade hooks rely on for partial-fill handling.
+     *
+     * @throws {PerpsError} `PerpsErrorCode.ExchangeRejected` carrying the venue
+     *   error when any returned result has `success: false`; also the errors
+     *   `execute` itself can throw (unregistered provider, no signer, signing
+     *   failure).
+     * @public
      */
-    async submitSignedOrder(params) {
-        return submitOrder(this.sdkClient, params);
+    async executeProviderOption(params) {
+        const { results } = await this.execute(params);
+        const failure = results.find((r) => !r.success);
+        if (failure) {
+            throw new PerpsError(PerpsErrorCode.ExchangeRejected, failure.error);
+        }
     }
     /**
-     * Build a withdrawal payload for the user to sign.
+     * Place a market or limit order. Convenience wrapper over {@link execute}
+     * with `ActionType.PLACE_ORDER`.
      *
-     * Withdrawals are user-signed only — agents cannot initiate withdrawals.
-     * No agent injection is performed regardless of signing mode.
+     * @throws {PerpsError} When the provider is unregistered or the action
+     *   cannot be signed/submitted.
+     * @example
+     * ```ts
+     * await client.placeOrder({
+     *   provider: 'hyperliquid',
+     *   address: '0xUser',
+     *   market: { symbol: 'ETH' },
+     *   side: 'buy',
+     *   size: '0.1',
+     * })
+     * ```
+     * @public
+     */
+    async placeOrder(params) {
+        return this.execute({ ...params, action: ActionType.PLACE_ORDER, params });
+    }
+    /**
+     * Place a trigger (take-profit / stop-loss) order. Convenience wrapper over
+     * {@link execute} with `ActionType.PLACE_TRIGGER_ORDER`.
      *
-     * @param params - Withdrawal parameters
-     * @returns Withdrawal action with typed data for signing
+     * @throws {PerpsError} When the provider is unregistered or the action
+     *   cannot be signed/submitted.
+     * @public
      */
-    async buildWithdrawal(params) {
-        return createWithdrawal(this.sdkClient, {
-            dex: params.dex,
-            address: params.address,
-            withdrawal: params.withdrawal,
+    async placeTriggerOrder(params) {
+        return this.execute({
+            ...params,
+            action: ActionType.PLACE_TRIGGER_ORDER,
+            params,
         });
     }
     /**
-     * Submit a signed withdrawal.
-     *
-     * Withdrawals are user-signed only — agents cannot initiate withdrawals.
+     * Cancel one or more open orders. Convenience wrapper over {@link execute}
+     * with `ActionType.CANCEL_ORDER`.
      *
-     * @param params - Signed withdrawal parameters
-     * @returns Withdrawal result
+     * @throws {PerpsError} When the provider is unregistered or the action
+     *   cannot be signed/submitted.
+     * @public
      */
-    async submitWithdrawal(params) {
-        return submitWithdrawal(this.sdkClient, params);
+    async cancelOrders(params) {
+        return this.execute({ ...params, action: ActionType.CANCEL_ORDER, params });
     }
     /**
-     * Determine which authorizations (if any) the user needs to sign before trading.
+     * Modify one or more open orders. Convenience wrapper over {@link execute}
+     * with `ActionType.MODIFY_ORDER`.
      *
-     * 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.
+     * @throws {PerpsError} When the provider is unregistered or the action
+     *   cannot be signed/submitted.
+     * @public
+     */
+    async modifyOrders(params) {
+        return this.execute({ ...params, action: ActionType.MODIFY_ORDER, params });
+    }
+    /**
+     * Add or remove isolated-position margin. Convenience wrapper over
+     * {@link execute} with `ActionType.UPDATE_POSITION_MARGIN`.
      *
-     * @param params - Parameters including dex, address, and dex-specific config
-     * @returns Which authorizations are needed and whether the user is ready to trade
+     * @throws {PerpsError} When the provider is unregistered or the action
+     *   cannot be signed/submitted.
+     * @public
      */
-    async getRequiredAuthorizations(params) {
-        const { dex, address } = params;
-        const mode = this.getSigningMode(address, dex);
-        const provider = getDexAuthProvider(dex);
-        // Ensure agent exists in USER_AGENT mode
-        let agentAddress;
-        if (mode === 'USER_AGENT') {
-            const agent = await this.sdkClient.agentManager.getOrCreateAgent(address, dex);
-            agentAddress = agent.address;
-        }
-        // Provider declares auth inputs categorized as user/agent
-        const authInputs = provider.getAuthorizationInputs({
-            signingMode: mode,
-            agentAddress,
+    async updatePositionMargin(params) {
+        return this.execute({
+            ...params,
+            action: ActionType.UPDATE_POSITION_MARGIN,
+            params,
         });
-        const allInputs = [...authInputs.user, ...authInputs.agent];
-        if (allInputs.length === 0) {
-            return { userAuthorizations: [], agentAuthorizations: [], isReady: true };
-        }
-        // Send ALL to backend — it filters already-satisfied ones and returns typed data
-        const { actions } = await this.buildAuthorization({
-            dex,
-            address,
-            authorizations: allInputs,
+    }
+    /**
+     * Withdraw funds from the provider account. Convenience wrapper over
+     * {@link execute} with `ActionType.WITHDRAWAL`.
+     *
+     * @throws {PerpsError} When the provider is unregistered or the action
+     *   cannot be signed/submitted.
+     * @public
+     */
+    async withdraw(params) {
+        return this.execute({
+            provider: params.provider,
+            address: params.address,
+            action: ActionType.WITHDRAWAL,
+            params: params.withdrawal,
         });
-        if (actions.length === 0) {
-            return { userAuthorizations: [], agentAuthorizations: [], 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));
-        return {
-            userAuthorizations,
-            agentAuthorizations,
-            isReady: false,
-        };
     }
     /**
-     * Execute authorizations: submit user-signed actions, then auto-sign and submit
-     * any agent authorizations.
+     * Execute any action through the SDK's signing pipeline: fetch the unsigned
+     * steps, delegate signing to the provider plugin (which branches on the
+     * descriptor's scheme and signer internally), and submit. Core stays
+     * signer-agnostic — the plugin owns WHO signs and HOW.
      *
-     * @param params - User-signed actions and the required authorizations result
-     * @returns Combined results from user and agent submissions
+     * @throws {PerpsError} When the action is not declared by the provider,
+     *   the plugin cannot sign it, or submission fails.
+     * @public
      */
-    async executeAuthorizations(params) {
-        const { dex, address, required, userSignedActions } = params;
-        const mode = this.getSigningMode(address, dex);
-        // 1. Submit user-signed actions (if any)
-        let userResults = { results: [] };
-        if (userSignedActions.length > 0) {
-            const signerAddress = mode === 'USER_AGENT'
-                ? (await this.sdkClient.agentManager.getAgent(address, dex)).address
-                : address;
-            userResults = await submitAuthorization(this.sdkClient, {
-                dex,
-                address,
-                signerAddress,
-                actions: userSignedActions,
-            });
-            // Check for failures - return early if any user auth failed
-            const failed = userResults.results.find((r) => !r.success);
-            if (failed) {
-                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);
-            const signedAgentActions = await Promise.all(required.agentAuthorizations.map(async (action) => ({
-                action: action.action,
-                typedData: action.typedData,
-                signature: await signTypedData(agent.privateKey, action.typedData),
-            })));
-            const agentResults = await submitAuthorization(this.sdkClient, {
-                dex,
-                address,
-                signerAddress: agent.address,
-                actions: signedAgentActions,
-            });
-            return { userResults, agentResults };
-        }
-        return { userResults };
+    async execute(params) {
+        const { provider, address, action } = params;
+        const metadata = await this.getProviderMetadata(provider);
+        const descriptor = findActionDescriptor(metadata, action);
+        const { signerAddress, params: signerParams } = await this.resolveActionRequest(provider, descriptor, address);
+        const { actions } = await createAction(this.sdkClient, {
+            provider,
+            address,
+            signerAddress,
+            action,
+            params: {
+                ...params.params,
+                ...signerParams,
+            },
+        });
+        const signedActions = await this.delegateSignActions(provider, address, descriptor, actions);
+        return executeAction(this.sdkClient, {
+            provider,
+            address,
+            // The submitting account: the plugin-resolved signer (Hyperliquid's
+            // agent) when present, else the end-user's address.
+            signerAddress: signerAddress ?? address,
+            action,
+            actions: signedActions,
+        });
     }
 }
 //# sourceMappingURL=PerpsClient.js.map