@lifi/perps-sdk 18.1.0 → 20.0.0

package/src/client/createPerpsClient.ts

@@ -1,10 +1,6 @@
 import type { PerpsConfig } from '../types/api.js'
-import type { PerpsBaseConfig, ProviderConfigs } from '../types/config.js'
-import type {
-  PerpsProvider,
-  PerpsProviderPlugin,
-  PerpsSDKClient,
-} from '../types/provider.js'
+import type { PerpsBaseConfig } from '../types/config.js'
+import type { PerpsProvider, PerpsSDKClient } from '../types/provider.js'
 import { bindProvider } from './bindProvider.js'
 
 /**
@@ -30,15 +26,12 @@ export const DEFAULT_API_URL = 'https://li.quest/v1/perps'
  */
 export function createPerpsClient(options: PerpsConfig): PerpsSDKClient {
   const apiUrl = options.apiUrl ?? DEFAULT_API_URL
-  const { providerPlugins, providerConfigs } = splitProviders(options.providers)
 
   const config: PerpsBaseConfig = {
     integrator: options.integrator?.trim() || undefined,
     apiKey: options.apiKey?.trim() ?? '',
     apiUrl,
-    disableVersionCheck: options.disableVersionCheck,
     requestInterceptor: options.requestInterceptor,
-    providers: providerConfigs,
     retry: options.retry,
     fetch: options.fetch,
   }
@@ -58,30 +51,9 @@ export function createPerpsClient(options: PerpsConfig): PerpsSDKClient {
     },
   }
 
-  const boundProviders: PerpsProvider[] = providerPlugins.map((plugin) =>
-    bindProvider(plugin, client)
+  const boundProviders: PerpsProvider[] = (options.providers ?? []).map(
+    (plugin) => bindProvider(plugin, client)
   )
 
   return client
 }
-
-/**
- * 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 function splitProviders(
-  input: PerpsProviderPlugin[] | ProviderConfigs | undefined
-): {
-  providerPlugins: PerpsProviderPlugin[]
-  providerConfigs?: ProviderConfigs
-} {
-  if (input === undefined) {
-    return { providerPlugins: [] }
-  }
-  if (Array.isArray(input)) {
-    return { providerPlugins: input }
-  }
-  return { providerPlugins: [], providerConfigs: input }
-}

package/src/client/requireProvider.ts

@@ -9,7 +9,7 @@ import type { PerpsProvider, PerpsSDKClient } from '../types/provider.js'
  * `createPerpsClient({ providers: [...] })`) rather than a runtime-recoverable
  * state.
  *
- * @internal
+ * @public
  */
 export function requireProvider(
   client: PerpsSDKClient,

package/src/index.ts

@@ -16,6 +16,7 @@ export {
   DEFAULT_API_URL,
 } from './client/createPerpsClient.js'
 export { PerpsClient } from './client/PerpsClient.js'
+export { requireProvider } from './client/requireProvider.js'
 export { PerpsErrorMessage } from './errors/constants.js'
 export { PerpsError } from './errors/PerpsError.js'
 // Registries
@@ -132,11 +133,8 @@ export type {
   WithdrawParams,
 } from './types/api.js'
 export type {
-  HyperliquidConfig,
   PerpsBaseConfig,
   PerpsClientSigner,
-  ProviderConfig,
-  ProviderConfigs,
   RequestInterceptor,
   SDKRequestOptions,
   SwitchChainHook,
@@ -222,6 +220,7 @@ export {
   formatSignedUsd,
   formatUsd,
 } from './utils/format.js'
+export { maxOf, minOf } from './utils/math.js'
 export {
   ACTIVE_ORDER_STATUSES,
   classifyFill,
@@ -241,7 +240,7 @@ export {
   findMatchingPosition,
   resolveCloseSize,
 } from './utils/orderMath.js'
-export { stringToFloat } from './utils/parse.js'
+export { parseDecimal, stringToFloat } from './utils/parse.js'
 export {
   directionSign,
   estimateIsolatedLiquidationPrice,
@@ -249,10 +248,14 @@ export {
   predictNewLeverage,
   predictUnrealizedPnl,
   realizedPnlOnClose,
+  wouldImmediatelyLiquidate,
 } from './utils/positionMath.js'
 export type { ScaleToIntegerPolicy } from './utils/scaleToInteger.js'
 export { scaleToInteger } from './utils/scaleToInteger.js'
-export { selectUserSetupActions } from './utils/setupActions.js'
+export {
+  isSetupOptionFor,
+  selectUserSetupActions,
+} from './utils/setupActions.js'
 export {
   signTypedData,
   signTypedDataWithSigner,

package/src/services/getOhlcv.ts

@@ -12,6 +12,7 @@ export interface GetOhlcvParams {
   provider: string
   /** Opaque provider `Market.id`, not a display symbol. */
   marketId: string
+  /** Pick from the provider's `Provider.supportedIntervals`; support varies per provider. */
   interval: OhlcvInterval
   /** Unix timestamp in milliseconds for the start bound. */
   startTime?: number

package/src/types/api.ts

@@ -15,7 +15,8 @@ import type {
   OrderSide,
   OrderType,
   PortfolioHistoryRange,
-  ProviderAction,
+  SetupAction,
+  SetupOption,
   SignedActionStep,
   TimeInForce,
   TriggerOrderInput,
@@ -23,11 +24,7 @@ import type {
 } from '@lifi/perps-types'
 import type { Account, Address, WalletClient } from 'viem'
 import type { RetryConfig } from '../transport/retryPolicy.js'
-import type {
-  ProviderConfigs,
-  RequestInterceptor,
-  SwitchChainHook,
-} from './config.js'
+import type { RequestInterceptor, SwitchChainHook } from './config.js'
 import type { PerpsProviderPlugin } from './provider.js'
 
 /**
@@ -51,28 +48,18 @@ export interface PerpsConfig {
   apiKey?: string
   /** Perps API base URL; defaults to {@link DEFAULT_API_URL}. */
   apiUrl?: string
-  /** Skip the SDK-version compatibility check when set. */
-  disableVersionCheck?: boolean
   /** Hook that can rewrite URL/request options before transport. */
   requestInterceptor?: RequestInterceptor
   /**
-   * Provider plugins or per-provider config. Two shapes are accepted:
-   *
-   * - `PerpsProviderPlugin[]` — plugin objects implementing the read surface
-   *   for one DEX each. Bound to the client at construction and looked up at
-   *   runtime as bound {@link PerpsProvider}s via `client.getProvider(key)`.
-   *   Modelled on `@lifi/sdk`'s `providers: SDKProvider[]`.
-   * - `ProviderConfigs` — keyed config object (e.g.
-   *   `{ hyperliquid: { markets: [...] } }`). Used internally by
-   *   `PerpsWsClient` to filter which markets are subscribed to.
-   *
-   * Both may be supplied during the migration to provider packages;
-   * the array form is preferred for new code.
+   * Provider plugins, one per DEX. Bound to the client at construction and
+   * looked up at runtime as bound {@link PerpsProvider}s via
+   * `client.getProvider(key)`. Modelled on `@lifi/sdk`'s
+   * `providers: SDKProvider[]`.
    */
-  providers?: PerpsProviderPlugin[] | ProviderConfigs
+  providers?: PerpsProviderPlugin[]
   /**
-   * The end-user's wallet, used whenever an action's descriptor names the user
-   * wallet in its `signers` list. Accepts any viem-compatible WalletClient:
+   * The end-user's wallet, used whenever an action's descriptor names
+   * `PerpsSigner.USER` as its `signer`. Accepts any viem-compatible WalletClient:
    *   - Browser wallet: wagmi's useWalletClient() result
    *   - Private key:    createWalletClient({ account: privateKeyToAccount('0x...'), transport: http() })
    *   - Mnemonic:       createWalletClient({ account: mnemonicToAccount('word1 ...'), transport: http() })
@@ -116,12 +103,8 @@ export interface PerpsClientOptions {
   apiKey?: string
   /** Perps API base URL; defaults to {@link DEFAULT_API_URL}. */
   apiUrl?: string
-  /**
-   * Provider plugins or per-provider config. Accepts the same two shapes as
-   * {@link PerpsConfig.providers}: an array of `PerpsProviderPlugin` plugins or
-   * a keyed `ProviderConfigs` map.
-   */
-  providers?: PerpsProviderPlugin[] | ProviderConfigs
+  /** Provider plugins; see {@link PerpsConfig.providers}. */
+  providers?: PerpsProviderPlugin[]
   /**
    * Hook invoked before a USER-signed EIP-712 action is signed, to switch the
    * user's wallet to the action's target chain. Also settable at runtime via
@@ -328,9 +311,21 @@ export interface GetPortfolioHistoryParams {
  */
 export interface SetupChecklistItem {
   /** The `Provider.setup` descriptor for this step. */
-  descriptor: ProviderAction
+  descriptor: SetupAction
   /** Whether the step is already satisfied for this account. */
   satisfied: boolean
+  /**
+   * For a choice step, the option whose bound params match the projected
+   * account value. `null` when none matches or the step is not a choice.
+   */
+  selected: SetupOption | null
+  /**
+   * For a choice step, the account's current value as the venue names it
+   * (the raw projected value, e.g. `standard` or `dexAbstraction`), even when
+   * no option binds it. `null` when the venue reports none or the value is
+   * unreadable, and always `null` for a non-choice step.
+   */
+  currentValue: string | null
 }
 
 /**
@@ -341,8 +336,10 @@ export interface SetupChecklistItem {
  * to the provider's `setup` descriptor, which declares the step's signer and
  * scheme), so no signer-role partition is exposed here.
  *
- * `Provider.options` items are NEVER included here — they don't gate trading
- * and are surfaced separately via `getAccount().settings`.
+ * A non-choice step with `signer: SDK` is NEVER included here — the SDK
+ * drains it itself. A choice step is listed on `checklist` but never staged or
+ * executed: the user picks an option through
+ * `PerpsClient.executeProviderOption`.
  *
  * @public
  */
@@ -356,12 +353,15 @@ export interface ProviderSetup {
   accountExists: boolean
   /** Unsatisfied setup steps, ordered by descriptor `sequence`. */
   setup: ActionStep[]
-  /** Whether all setup items are already satisfied (ready to trade) */
+  /**
+   * `true` only when nothing is staged and every choice on `checklist` is
+   * satisfied: the account is ready to trade.
+   */
   isReady: boolean
   /**
-   * The renderable onboarding list: every USER-signed setup descriptor with
-   * its satisfied state, ordered by `sequence`. SDK-internal steps and
-   * conditional steps that staged no work for this account (see
+   * The renderable onboarding list: every choice step and every `USER`-signed
+   * setup step with its satisfied state, ordered by `sequence`. SDK-drained
+   * steps and conditional steps that staged no work for this account (see
    * `PerpsProviderPlugin.conditionalSetupActions`) are omitted. Consumers
    * render this list directly instead of joining `Provider.setup` metadata
    * with the staged `setup` steps.
@@ -393,14 +393,14 @@ export interface ExecuteProviderSetupResult {
  * backend's `AccountResponse` with a single SDK-projected `settings` array.
  *
  * `settings` contains exactly one `AccountConfigSetting` per descriptor on
- * `Provider.setup` + `Provider.options` (in that order). Index the
- * projection by `setting.type === descriptor.type` and read
- * `setting.values[i].value` for each `Param` the descriptor declared.
+ * `Provider.setup`, in that order. Index the projection by
+ * `setting.type === descriptor.type` and read `setting.values[i].value` for
+ * each `Param` the descriptor declared.
  *
  * @public
  */
 export interface GetAccountResult extends AccountResponse {
-  /** SDK-projected current state of every setup + options descriptor. */
+  /** SDK-projected current state of every `Provider.setup` descriptor. */
   settings: AccountConfigSetting[]
 }
 

package/src/types/config.ts

@@ -23,32 +23,6 @@ export type SwitchChainHook = (
   chainId: number
 ) => Promise<PerpsClientSigner | undefined>
 
-/**
- * Per-provider config — restricts which `markets` the WS client subscribes
- * to. Indexed by provider key.
- *
- * @public
- */
-export interface ProviderConfig {
-  /** Optional provider category/market ids used to filter WS subscriptions. */
-  markets?: string[]
-}
-
-/**
- * @deprecated Use {@link ProviderConfig}.
- * @public
- */
-export type HyperliquidConfig = ProviderConfig
-
-/**
- * Map of per-provider {@link ProviderConfig}, keyed by provider key.
- *
- * @public
- */
-export interface ProviderConfigs {
-  [provider: string]: ProviderConfig | undefined
-}
-
 /**
  * Hook to rewrite each outgoing request's URL/`RequestInit` before it is sent.
  *
@@ -101,12 +75,8 @@ export interface PerpsBaseConfig {
   apiKey: string
   /** Resolved perps API base URL. */
   apiUrl: string
-  /** Whether SDK version compatibility checks are disabled. */
-  disableVersionCheck?: boolean
   /** Optional outgoing-request URL/options interceptor. */
   requestInterceptor?: RequestInterceptor
-  /** Optional per-provider WS market filters. */
-  providers?: ProviderConfigs
   /** Optional global or per-provider retry configuration. */
   retry?: RetryConfig
   /** Fetch implementation used by core HTTP transport. */

package/src/types/provider.ts

@@ -22,9 +22,9 @@ import type {
   PortfolioHistoryResponse,
   Position,
   PositionsResponse,
-  ProviderAction,
   Quote,
   QuoteSide,
+  SetupAction,
   SignedActionStep,
   SigningMethod,
   TradeType,
@@ -86,12 +86,12 @@ export interface SignActionsContext {
   /** End-user wallet used for USER-signed or EVM transaction legs. */
   userWallet?: PerpsClientSigner
   /**
-   * The signing batch's declared signers, from the action's `ProviderAction`
+   * The signing batch's declared signer, from the action's `ProviderAction`
    * descriptor. The plugin branches on this to pick WHO signs (e.g.
-   * Hyperliquid: `USER` → end-user wallet, `AGENT` → session keypair). Core
-   * forwards the descriptor's `signers` as data; it does not branch on them.
+   * Hyperliquid: `USER` → end-user wallet, `SDK` → session keypair). Core
+   * forwards the descriptor's `signer` as data; it does not branch on it.
    */
-  signers?: PerpsSigner[]
+  signer?: PerpsSigner
   /**
    * Switch `userWallet` to `chainId` and resolve the client to broadcast with.
    * Bound by core to the consumer's `switchChain` hook and the resolved
@@ -370,23 +370,12 @@ export interface PerpsProviderPlugin {
   readonly type: string
 
   /**
-   * Setup actions the provider completes on its own, without surfacing a card
-   * to the caller. `PerpsClient.checkSetup` drains each such pending step in
-   * place — building, signing, and executing it with the provider's own
-   * credentials — and omits it from the returned `setup` list. A descriptor
-   * whose `signers` include {@link PerpsSigner.USER} is never treated as
-   * internal, even when named here. Omit when the provider has no
-   * self-completed setup steps.
-   */
-  readonly internalSetupActions?: readonly ActionType[]
-
-  /**
-   * Setup actions that stage work only when the account needs remediation
-   * (e.g. Hyperliquid's REVOKE_AGENT frees an agent slot only when every
-   * named slot is taken). When such a step stages no actions,
+   * Non-choice setup actions that stage work only when the account needs
+   * remediation (e.g. Hyperliquid's REVOKE_AGENT frees an agent slot only
+   * when every named slot is taken). When such a step stages no actions,
    * `PerpsClient.checkSetup` omits it from `ProviderSetup.checklist` instead
-   * of rendering it as satisfied. Omit when every setup step is
-   * unconditional.
+   * of rendering it as satisfied. Choices are always rendered because they
+   * are never staged. Omit when every setup step is unconditional.
    */
   readonly conditionalSetupActions?: readonly ActionType[]
 
@@ -464,16 +453,17 @@ export interface PerpsProviderPlugin {
   ): Promise<PositionsResponse>
 
   /**
-   * The user's current venue-side settings for one market — the margin mode
-   * and leverage the next order on it will use. Optional because venues
-   * expose this unevenly: Hyperliquid reads it directly (`activeAssetData`),
-   * Lighter only reports it on an account's position row. `undefined` means
-   * the venue has nothing to read for this market.
+   * The user's current venue-side settings for one perps market — the margin
+   * mode and leverage the next order on it will use. Resolves the venue value
+   * or throws.
+   *
+   * @throws {PerpsError} `ValidationError` for a spot market; any other
+   *   `PerpsError` when the venue read fails or carries no usable value.
    */
-  getMarketSettings?(
+  getMarketSettings(
     params: ProviderGetMarketSettingsParams,
     options?: SDKRequestOptions
-  ): Promise<MarketSettings | undefined>
+  ): Promise<MarketSettings>
 
   /**
    * The amounts the account can still buy and sell on one market, in that
@@ -598,9 +588,12 @@ export interface PerpsProviderPlugin {
 
   /**
    * Project a typed {@link AccountConfig} against the provider's `setup`
-   * + `options` descriptors into `AccountConfigSetting[]`. Used by
+   * descriptors into `AccountConfigSetting[]`. Used by
    * `PerpsClient.getAccount` to attach a `settings` array to the response —
-   * one entry per descriptor, in `setup`-then-`options` order.
+   * one entry per descriptor, in `setup` order. Every choice descriptor
+   * (`options` is not `null`) carries a boolean `satisfied`, because
+   * `PerpsClient.checkSetup` reads a choice's satisfied state and `selected`
+   * option from this projection alone.
    *
    * Implementations receive the union-typed `AccountConfig` and narrow on
    * `config.provider` themselves; the dispatcher in `PerpsClient` does not
@@ -608,8 +601,7 @@ export interface PerpsProviderPlugin {
    */
   projectConfig(
     config: AccountConfig,
-    setup: ProviderAction[],
-    options: ProviderAction[]
+    setup: SetupAction[]
   ): AccountConfigSetting[]
 
   /**
@@ -617,7 +609,8 @@ export interface PerpsProviderPlugin {
    * when staging the provider setup. Used for plugin-side state the backend
    * needs to make a correct idempotency decision (e.g. Lighter's known local
    * API public key). Returns an empty object when the plugin has no params
-   * to contribute for the action. Optional — providers without local state
+   * to contribute for the action. A choice option runs with its bound params
+   * alone and never reads these. Optional — providers without local state
    * can omit it entirely.
    */
   resolveSetupParams?(
@@ -628,7 +621,7 @@ export interface PerpsProviderPlugin {
   /**
    * Contribute the signer-bearing wire fields for an action — the plugin owns
    * signer identity (WHO signs), so core asks the plugin rather than resolving
-   * a `signerAddress` itself. The descriptor's `signers` are forwarded so the
+   * a `signerAddress` itself. The descriptor's `signer` is forwarded so the
    * plugin can branch on signer role: a provider that signs on the user's
    * behalf with a session keypair (Hyperliquid's agent) resolves — provisioning
    * one if needed — and returns the agent address as `signerAddress`; for
@@ -644,7 +637,7 @@ export interface PerpsProviderPlugin {
   resolveActionRequest?(
     action: ActionType,
     address: Address,
-    signers: PerpsSigner[]
+    signer: PerpsSigner
   ): Promise<ActionSignerContribution>
 
   /**
@@ -659,7 +652,7 @@ export interface PerpsProviderPlugin {
    * provider has no `signActions`.
    *
    * `method` mirrors the descriptor's `signingMethod`. The plugin owns every
-   * arm, branching on the descriptor's `signers` internally: the EIP712 arm
+   * arm, branching on the descriptor's `signer` internally: the EIP712 arm
    * signs with the user's wallet (read from `ctx.userWallet`) or the provider's
    * session keypair (Hyperliquid's agent), and `WASM_BLOB` / `EVM_TX` sign with
    * the provider's local credential (Lighter).

package/src/types/withdrawal.ts

@@ -1,15 +1,7 @@
-import type { ActionType, Asset } from '@lifi/perps-types'
+import type { ActionType, Asset, WithdrawalRoute } from '@lifi/perps-types'
 import type { Address } from 'viem'
 
-/**
- * Which of a venue's two balance routes a withdrawal is drawn from. Lighter's
- * own vocabulary, carried in the signed tx as `AssetRouteType` (`perps` = 0,
- * `spot` = 1); an account's mode changes what the two balances mean, never
- * which route the tx names.
- *
- * @public
- */
-export type WithdrawalRoute = 'perps' | 'spot'
+export type { WithdrawalRoute }
 
 /**
  * One withdrawable `(asset, route)` selection as the provider reports it, keyed
@@ -25,10 +17,16 @@ export interface ProviderWithdrawableBalance {
   available: string
   /**
    * Flat venue fee on a withdrawal from this row, in the asset's own units.
-   * Absent when the venue publishes no fee for the asset. The client rejects a
-   * value that is not a non-negative decimal.
+   * Absent when the venue publishes no fee for the asset. The client rejects
+   * a value that is not a non-negative decimal.
    */
   withdrawalFee?: string
+  /**
+   * `true` when the venue takes `withdrawalFee` out of the requested amount,
+   * `false` when it charges the fee in addition. Set together with
+   * `withdrawalFee`; the client drops it from a row without a fee.
+   */
+  isFeeDeducted?: boolean
 }
 
 /**
@@ -44,11 +42,22 @@ export interface WithdrawableBalance {
   /** Withdrawable amount in the asset's own units. */
   available: string
   /**
-   * Flat venue fee on a withdrawal from this row, in the asset's own units. An
-   * amount at or below it delivers nothing. Absent when the venue publishes no
-   * fee for the asset.
+   * Flat venue fee on a withdrawal from this row, in the asset's own units.
+   * Absent when the venue publishes no fee for the asset. With
+   * `isFeeDeducted` `true`, the venue takes the fee out of the requested
+   * amount, and an amount at or below the fee delivers nothing. With `false`,
+   * the venue charges the fee in addition to the requested amount, so the
+   * largest amount the row can fund is `available` minus the fee. That result
+   * is zero or negative when the fee is at or above `available`, and the row
+   * then funds no withdrawal.
    */
   withdrawalFee?: string
+  /**
+   * Present only together with `withdrawalFee`. Absent on a row from a
+   * provider plugin that does not report it; absence means unknown, not
+   * `true`.
+   */
+  isFeeDeducted?: boolean
 }
 
 /**