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

package/dist/types/client/PerpsClient.d.ts

@@ -1,198 +1,285 @@
-import type { Address, AuthorizationsResponse, CancelOrderPayloadResponse, CreateAuthorizationResponse, CreateOrderResponse, CreateWithdrawalResponse, SubmitOrderResponse, SubmitWithdrawalResponse } from '@lifi/perps-types';
-import type { SubmitAuthorizationParams } from '../services/submitAuthorization.js';
-import type { SubmitOrderParams } from '../services/submitOrder.js';
-import type { SubmitWithdrawalParams } from '../services/submitWithdrawal.js';
-import { type PerpsSDKClient } from './createPerpsClient.js';
-import type { BuildAuthorizationParams, BuildWithdrawalParams, CancelOrdersParams, ExecuteAuthorizationsParams, ExecuteAuthorizationsResult, GetRequiredAuthorizationsParams, PerpsClientOptions, PlaceOrderParams, RequiredAuthorizationsResult, SigningMode } from './types.js';
+import type { AccountResponse, AccountSummary, ActionParamsMap, ActionStep, CreateActionResponse, ExecuteActionResponse, MarketRef, Position, SignedActionStep } from '@lifi/perps-types';
+import { ActionType } from '@lifi/perps-types';
+import type { Address } from 'viem';
+import type { BuildProviderSetupParams, CancelOrdersParams, ExecuteProviderSetupParams, ExecuteProviderSetupResult, GetAccountResult, GetSetupParams, ModifyOrdersParams, PerpsClientOptions, PlaceOrderParams, PlaceTriggerOrderParams, ProviderSetup, WithdrawParams } from '../types/api.js';
+import type { PerpsSDKClient } from '../types/provider.js';
 /**
- * Stateful client for managing signing modes and trading operations.
+ * 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.
  *
- * 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'
- * })
- * ```
+ * @public
  */
 export declare class PerpsClient {
     private sdkClient;
-    private signingModes;
+    private providerMetadataCache;
+    private _userWallet;
     constructor(options: PerpsClientOptions);
     /**
-     * Get the underlying SDK client for use with service functions.
-     */
-    get client(): PerpsSDKClient;
-    /**
-     * 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
      */
-    private modeKey;
+    setUserWallet(userWallet: PerpsSDKClient['userWallet']): void;
     /**
-     * Set the signing mode for a user + DEX pair.
-     *
-     * In `USER_AGENT` mode, generates an agent keypair if one doesn't exist.
+     * The underlying low-level {@link PerpsSDKClient} (config, user wallet,
+     * provider registry) backing this instance.
      *
-     * @param address - User wallet address
-     * @param dex - DEX identifier
-     * @param mode - Signing mode to set
+     * @public
      */
-    setSigningMode(address: Address, dex: string, mode: SigningMode): Promise<void>;
+    get client(): PerpsSDKClient;
+    private getProviderMetadata;
     /**
-     * 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: Address, dex: string): SigningMode;
+    private requireProvider;
     /**
-     * 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.
      */
-    getAgentAddress(address: Address, dex: string): Promise<Address>;
+    private resolveActionRequest;
     /**
-     * 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.
      */
-    hasAgent(address: Address, dex: string): Promise<boolean>;
+    private delegateSignActions;
     /**
-     * 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.
      */
-    removeAgent(address: Address, dex: string): Promise<void>;
+    private buildSignActionsContext;
     /**
-     * Build authorization payloads for signing.
-     *
-     * In `USER` mode, `signerAddress` is omitted (backend defaults to `address`).
-     * In `USER_AGENT` mode, auto-injects the agent address as `signerAddress`.
+     * 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.
      *
-     * @param params - Authorization parameters
-     * @returns Authorization actions with typed data for signing
+     * @throws {PerpsError} When the step's action is not declared by the provider.
+     * @public
      */
-    buildAuthorization(params: BuildAuthorizationParams): Promise<CreateAuthorizationResponse>;
+    signProviderSetupAction(provider: string, address: Address, step: ActionStep): Promise<SignedActionStep>;
     /**
-     * Submit signed authorizations.
+     * Build (but do not sign or submit) the unsigned action steps for `action`,
+     * letting the provider plugin contribute any signer-bearing request fields.
      *
-     * 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
+     * @public
      */
-    submitAuthorizations(params: SubmitAuthorizationParams): Promise<AuthorizationsResponse>;
+    buildAction<T extends ActionType>(action: T, params: {
+        provider: string;
+        address: Address;
+        params: ActionParamsMap[T];
+    }): Promise<CreateActionResponse>;
     /**
-     * Build order payloads 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`.
      *
-     * 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
+     */
+    getAccount(params: {
+        provider: string;
+        address: Address;
+    }): Promise<GetAccountResult>;
+    /**
+     * 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: AccountResponse, positions: Position[]): AccountSummary;
+    /**
+     * 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 - Order parameters
-     * @returns Order actions with typed data for signing
+     * @throws {PerpsError} On any backend error other than
+     *   `PerpsErrorCode.AccountNotFound`.
+     * @public
      */
-    buildOrder(params: PlaceOrderParams): Promise<CreateOrderResponse>;
+    accountExists(provider: string, address: Address): Promise<boolean>;
     /**
-     * Build cancel 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 - Cancel parameters
-     * @returns Cancel actions with typed data for signing
+     * @public
      */
-    buildCancelOrder(params: CancelOrdersParams): Promise<CancelOrderPayloadResponse>;
+    checkSetup(params: GetSetupParams): Promise<ProviderSetup>;
     /**
-     * Place an order with automatic agent 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).
      *
-     * **Requires USER_AGENT mode.** For USER mode, use `buildOrder()` + `submitSignedOrder()`.
+     * @public
+     */
+    buildProviderSetup(params: BuildProviderSetupParams): Promise<CreateActionResponse>;
+    /**
+     * 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
      */
-    placeOrder(params: PlaceOrderParams): Promise<SubmitOrderResponse>;
+    executeProviderSetup(params: ExecuteProviderSetupParams): Promise<ExecuteProviderSetupResult>;
     /**
-     * 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
      */
-    cancelOrders(params: CancelOrdersParams): Promise<SubmitOrderResponse>;
+    executeProviderSetupAction(params: {
+        provider: string;
+        address: Address;
+        step: ActionStep;
+    }): Promise<void>;
     /**
-     * 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
      */
-    submitSignedOrder(params: SubmitOrderParams): Promise<SubmitOrderResponse>;
+    executeProviderOption<T extends ActionType>(params: {
+        provider: string;
+        address: Address;
+        action: T;
+        params: ActionParamsMap[T];
+    }): Promise<void>;
     /**
-     * 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
+     */
+    placeOrder(params: PlaceOrderParams): Promise<ExecuteActionResponse>;
+    /**
+     * 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
      */
-    buildWithdrawal(params: BuildWithdrawalParams): Promise<CreateWithdrawalResponse>;
+    placeTriggerOrder(params: PlaceTriggerOrderParams): Promise<ExecuteActionResponse>;
     /**
-     * Submit a signed withdrawal.
+     * Cancel one or more open orders. Convenience wrapper over {@link execute}
+     * with `ActionType.CANCEL_ORDER`.
      *
-     * Withdrawals are user-signed only — agents cannot initiate withdrawals.
+     * @throws {PerpsError} When the provider is unregistered or the action
+     *   cannot be signed/submitted.
+     * @public
+     */
+    cancelOrders(params: CancelOrdersParams): Promise<ExecuteActionResponse>;
+    /**
+     * Modify one or more open orders. Convenience wrapper over {@link execute}
+     * with `ActionType.MODIFY_ORDER`.
      *
-     * @param params - Signed withdrawal parameters
-     * @returns Withdrawal result
+     * @throws {PerpsError} When the provider is unregistered or the action
+     *   cannot be signed/submitted.
+     * @public
      */
-    submitWithdrawal(params: SubmitWithdrawalParams): Promise<SubmitWithdrawalResponse>;
+    modifyOrders(params: ModifyOrdersParams): Promise<ExecuteActionResponse>;
     /**
-     * Determine which authorizations (if any) the user needs to sign before trading.
+     * Add or remove isolated-position margin. Convenience wrapper over
+     * {@link execute} with `ActionType.UPDATE_POSITION_MARGIN`.
      *
-     * 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
+     */
+    updatePositionMargin(params: {
+        provider: string;
+        address: Address;
+        market: MarketRef;
+        action: 'add' | 'remove';
+        amount: string;
+    }): Promise<ExecuteActionResponse>;
+    /**
+     * Withdraw funds from the provider account. Convenience wrapper over
+     * {@link execute} with `ActionType.WITHDRAWAL`.
      *
-     * @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
      */
-    getRequiredAuthorizations(params: GetRequiredAuthorizationsParams): Promise<RequiredAuthorizationsResult>;
+    withdraw(params: WithdrawParams): Promise<ExecuteActionResponse>;
     /**
-     * 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
      */
-    executeAuthorizations(params: ExecuteAuthorizationsParams): Promise<ExecuteAuthorizationsResult>;
+    execute<T extends ActionType>(params: {
+        provider: string;
+        address: Address;
+        action: T;
+        params: ActionParamsMap[T];
+    }): Promise<ExecuteActionResponse>;
 }
 //# sourceMappingURL=PerpsClient.d.ts.map

package/dist/types/client/PerpsClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PerpsClient.d.ts","sourceRoot":"","sources":["../../../src/client/PerpsClient.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"PerpsClient.d.ts","sourceRoot":"","sources":["../../../src/client/PerpsClient.ts"],"names":[],"mappings":"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"}

package/dist/types/client/bindProvider.d.ts

@@ -0,0 +1,13 @@
+import type { PerpsProvider, PerpsProviderPlugin, PerpsSDKClient } from '../types/provider.js';
+/**
+ * Inject `client` into a {@link PerpsProviderPlugin} once via its
+ * {@link PerpsProviderPlugin.bind} hook, returning the runtime
+ * {@link PerpsProvider} — the plugin with its one-shot `bind` member dropped so
+ * consumers cannot re-bind a live provider. The read methods are already
+ * clientless (`getX(params, options?)`); they resolve their runtime deps from
+ * the context the plugin captured during `bind`.
+ *
+ * @internal
+ */
+export declare function bindProvider(plugin: PerpsProviderPlugin, client: PerpsSDKClient): PerpsProvider;
+//# sourceMappingURL=bindProvider.d.ts.map

package/dist/types/client/bindProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bindProvider.d.ts","sourceRoot":"","sources":["../../../src/client/bindProvider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,mBAAmB,EACnB,cAAc,EACf,MAAM,sBAAsB,CAAA;AAE7B;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,mBAAmB,EAC3B,MAAM,EAAE,cAAc,GACrB,aAAa,CAIf"}

package/dist/types/client/createPerpsClient.d.ts

@@ -1,77 +1,37 @@
-import { AgentManager } from '../agent/AgentManager.js';
-import type { StorageAdapter } from '../agent/types.js';
-export declare const DEFAULT_API_URL = "https://develop.li.quest/v1/perps";
-/**
- * Configuration options for creating a Perps SDK client.
- */
-export interface PerpsConfig {
-    /** Integrator identifier (required) */
-    integrator: string;
-    /** Optional API key for authenticated requests */
-    apiKey?: string;
-    /** Base API URL. Defaults to DEFAULT_API_URL */
-    apiUrl?: string;
-    /** Disable version update check in development mode */
-    disableVersionCheck?: boolean;
-    /** Custom storage adapter for agent keys. Defaults to localStorage. */
-    storage?: StorageAdapter;
-    /** Optional request interceptor for custom handling */
-    requestInterceptor?: RequestInterceptor;
-}
-/**
- * Resolved configuration with required fields.
- */
-export interface PerpsBaseConfig {
-    /** Integrator identifier (required) */
-    integrator: string;
-    /** Optional API key for authenticated requests */
-    apiKey?: string;
-    /** Resolved API URL (always set) */
-    apiUrl: string;
-    /** Disable version update check in development mode */
-    disableVersionCheck?: boolean;
-    /** Optional request interceptor for custom handling */
-    requestInterceptor?: RequestInterceptor;
-}
-/**
- * Request interceptor function type.
- * Called before each request is made, allowing modification of fetch options.
- */
-export type RequestInterceptor = (url: string, options: RequestInit) => RequestInit | Promise<RequestInit>;
+import type { PerpsConfig } from '../types/api.js';
+import type { ProviderConfigs } from '../types/config.js';
+import type { PerpsProviderPlugin, PerpsSDKClient } from '../types/provider.js';
 /**
- * Options passed to service functions for request control.
- */
-export interface SDKRequestOptions {
-    /** AbortSignal to cancel the request */
-    signal?: AbortSignal;
-}
-/**
- * The Perps SDK client instance.
- * Holds configuration and agent manager for making API requests.
+ * Default LI.FI perps API base URL used when `PerpsConfig.apiUrl` is omitted.
+ *
+ * @public
  */
-export interface PerpsSDKClient {
-    /** SDK configuration */
-    readonly config: PerpsBaseConfig;
-    /** Agent manager for USER_AGENT signing mode */
-    readonly agentManager: AgentManager;
-}
+export declare const DEFAULT_API_URL = "https://develop.li.quest/v1/perps";
 /**
- * Create a new Perps SDK client.
- *
- * @param options - Configuration options
- * @returns A new SDK client instance
- * @throws {PerpsError} If integrator is not provided
+ * Construct the low-level {@link PerpsSDKClient} — config, the optional
+ * end-user wallet, and provider registry — shared by the service functions and
+ * the higher-level {@link PerpsClient}.
  *
+ * @throws {PerpsError} When `options.integrator` is missing.
  * @example
  * ```ts
  * const client = createPerpsClient({
  *   integrator: 'my-app',
- *   apiKey: 'optional-api-key',
+ *   apiKey: 'key',
+ *   providers: [hyperliquidProvider()],
  * })
- *
- * // Use with service functions
- * const { dexes } = await getDexes(client)
  * ```
+ * @public
  */
 export declare function createPerpsClient(options: PerpsConfig): PerpsSDKClient;
+/**
+ * Split the overloaded `providers` option into its two shapes — the
+ * plugin array used by {@link PerpsSDKClient.getProvider}, and the
+ * keyed `ProviderConfigs` consumed internally by `PerpsWsClient` for
+ * markets filtering.
+ */
+export declare function splitProviders(input: PerpsProviderPlugin[] | ProviderConfigs | undefined): {
+    providerPlugins: PerpsProviderPlugin[];
+    providerConfigs?: ProviderConfigs;
+};
 //# sourceMappingURL=createPerpsClient.d.ts.map

package/dist/types/client/createPerpsClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createPerpsClient.d.ts","sourceRoot":"","sources":["../../../src/client/createPerpsClient.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AACvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAIvD,eAAO,MAAM,eAAe,sCAAsC,CAAA;AAElE;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAA;IAClB,kDAAkD;IAClD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,gDAAgD;IAChD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,uDAAuD;IACvD,mBAAmB,CAAC,EAAE,OAAO,CAAA;IAC7B,uEAAuE;IACvE,OAAO,CAAC,EAAE,cAAc,CAAA;IACxB,uDAAuD;IACvD,kBAAkB,CAAC,EAAE,kBAAkB,CAAA;CACxC;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAA;IAClB,kDAAkD;IAClD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAA;IACd,uDAAuD;IACvD,mBAAmB,CAAC,EAAE,OAAO,CAAA;IAC7B,uDAAuD;IACvD,kBAAkB,CAAC,EAAE,kBAAkB,CAAA;CACxC;AAED;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAC/B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,WAAW,KACjB,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;AAEvC;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,wCAAwC;IACxC,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,wBAAwB;IACxB,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAA;IAChC,gDAAgD;IAChD,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAA;CACpC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,WAAW,GAAG,cAAc,CA8BtE"}
+{"version":3,"file":"createPerpsClient.d.ts","sourceRoot":"","sources":["../../../src/client/createPerpsClient.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAClD,OAAO,KAAK,EAAmB,eAAe,EAAE,MAAM,oBAAoB,CAAA;AAC1E,OAAO,KAAK,EAEV,mBAAmB,EACnB,cAAc,EACf,MAAM,sBAAsB,CAAA;AAG7B;;;;GAIG;AACH,eAAO,MAAM,eAAe,sCAAsC,CAAA;AAElE;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,WAAW,GAAG,cAAc,CA4CtE;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,mBAAmB,EAAE,GAAG,eAAe,GAAG,SAAS,GACzD;IACD,eAAe,EAAE,mBAAmB,EAAE,CAAA;IACtC,eAAe,CAAC,EAAE,eAAe,CAAA;CAClC,CAQA"}

package/dist/types/client/requireProvider.d.ts

@@ -0,0 +1,12 @@
+import type { PerpsProvider, PerpsSDKClient } from '../types/provider.js';
+/**
+ * Resolve the registered bound {@link PerpsProvider} for `provider`, or throw.
+ * Account reads run direct-to-venue through the provider, so a missing one is a
+ * wiring error (the consumer must pass it to
+ * `createPerpsClient({ providers: [...] })`) rather than a runtime-recoverable
+ * state.
+ *
+ * @internal
+ */
+export declare function requireProvider(client: PerpsSDKClient, provider: string): PerpsProvider;
+//# sourceMappingURL=requireProvider.d.ts.map

package/dist/types/client/requireProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"requireProvider.d.ts","sourceRoot":"","sources":["../../../src/client/requireProvider.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAEzE;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,MAAM,GACf,aAAa,CAYf"}

package/dist/types/errors/PerpsError.d.ts

@@ -1,9 +1,16 @@
 import { PerpsErrorCode } from '@lifi/perps-types';
-import { PerpsErrorName } from './constants.js';
+/**
+ * Error thrown by every SDK code path — backend error responses, transport
+ * failures, and SDK-side validation alike. Carries a {@link PerpsErrorCode}
+ * for programmatic branching and an optional `tool` tag identifying the
+ * originating package.
+ *
+ * @public
+ */
 export declare class PerpsError extends Error {
     code: PerpsErrorCode;
-    name: PerpsErrorName;
+    name: string;
+    tool?: string;
     constructor(code?: PerpsErrorCode, message?: string);
-    static fromError(error: unknown, defaultCode?: PerpsErrorCode): PerpsError;
 }
 //# sourceMappingURL=PerpsError.d.ts.map

package/dist/types/errors/PerpsError.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PerpsError.d.ts","sourceRoot":"","sources":["../../../src/errors/PerpsError.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAElD,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAE/C,qBAAa,UAAW,SAAQ,KAAK;IACnC,IAAI,EAAE,cAAc,CAAA;IACX,IAAI,iBAA4B;gBAGvC,IAAI,GAAE,cAA4C,EAClD,OAAO,SAA2B;IAQpC,MAAM,CAAC,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,WAAW,CAAC,EAAE,cAAc,GAAG,UAAU;CAe3E"}
+{"version":3,"file":"PerpsError.d.ts","sourceRoot":"","sources":["../../../src/errors/PerpsError.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAElD;;;;;;;GAOG;AACH,qBAAa,UAAW,SAAQ,KAAK;IACnC,IAAI,EAAE,cAAc,CAAA;IACX,IAAI,SAAe;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAA;gBAGX,IAAI,GAAE,cAA4C,EAClD,OAAO,SAA2B;CAKrC"}