@lifi/perps-sdk 0.2.0-alpha.0 → 1.0.1

package/src/client/bindProvider.ts

@@ -0,0 +1,24 @@
+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 function bindProvider(
+  plugin: PerpsProviderPlugin,
+  client: PerpsSDKClient
+): PerpsProvider {
+  plugin.bind(client)
+  const { bind: _bind, ...provider } = plugin
+  return provider
+}

package/src/client/createPerpsClient.ts

@@ -1,72 +1,37 @@
 import { PerpsErrorCode } from '@lifi/perps-types'
-import type { Account, WalletClient } from 'viem'
-import { AgentManager } from '../agent/AgentManager.js'
-import type { StorageAdapter } from '../agent/types.js'
 import { PerpsError } from '../errors/PerpsError.js'
+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 { bindProvider } from './bindProvider.js'
 
+/**
+ * Default LI.FI perps API base URL used when `PerpsConfig.apiUrl` is omitted.
+ *
+ * @public
+ */
 export const DEFAULT_API_URL = 'https://develop.li.quest/v1/perps'
 
-export interface ProviderConfig {
-  markets?: string[]
-}
-
-/** @deprecated Use ProviderConfig */
-export type HyperliquidConfig = ProviderConfig
-
-export interface ProviderConfigs {
-  [provider: string]: ProviderConfig | undefined
-}
-
-export interface PerpsConfig {
-  integrator: string
-  apiKey: string
-  apiUrl?: string
-  disableVersionCheck?: boolean
-  storage?: StorageAdapter
-  requestInterceptor?: RequestInterceptor
-  providers?: ProviderConfigs
-  /**
-   * Wallet signer used whenever an action's descriptor names the user wallet
-   * in its `signers` list. 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() })
-   */
-  signer?: WalletClient<any, any, Account>
-}
-
-export interface PerpsBaseConfig {
-  integrator: string
-  apiKey: string
-  apiUrl: string
-  disableVersionCheck?: boolean
-  requestInterceptor?: RequestInterceptor
-  providers?: ProviderConfigs
-}
-
-export type RequestInterceptor = (
-  url: string,
-  options: RequestInit
-) => RequestInit | Promise<RequestInit>
-
-export interface SDKRequestOptions {
-  signal?: AbortSignal
-  /**
-   * Lighter auth token for authenticated read endpoints (getOrders, getOrder,
-   * getActivity). Mint via `lighterSigner.createAuthToken(deadline, context)`.
-   * Forwarded as `Authorization: Bearer <token>` and never persisted by the
-   * backend — read-only by design (8h max TTL, cannot authorize writes).
-   */
-  lighterAuthToken?: string
-}
-
-export interface PerpsSDKClient {
-  readonly config: PerpsBaseConfig
-  readonly agentManager: AgentManager
-  /** Wallet signer for setup actions — accepts any viem WalletClient (browser, private key, mnemonic). */
-  readonly signer?: WalletClient<any, any, Account>
-}
-
+/**
+ * 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: 'key',
+ *   providers: [hyperliquidProvider()],
+ * })
+ * ```
+ * @public
+ */
 export function createPerpsClient(options: PerpsConfig): PerpsSDKClient {
   if (!options.integrator) {
     const error = new PerpsError(
@@ -78,6 +43,7 @@ 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,
@@ -85,20 +51,50 @@ export function createPerpsClient(options: PerpsConfig): PerpsSDKClient {
     apiUrl,
     disableVersionCheck: options.disableVersionCheck,
     requestInterceptor: options.requestInterceptor,
-    providers: options.providers,
+    providers: providerConfigs,
+    retry: options.retry,
+    fetch: options.fetch,
   }
 
-  const agentManager = new AgentManager(options.storage)
-
-  return {
+  const client: PerpsSDKClient = {
     get config() {
       return config
     },
-    get agentManager() {
-      return agentManager
+    get userWallet() {
+      return options.userWallet
+    },
+    get providers() {
+      return boundProviders
     },
-    get signer() {
-      return options.signer
+    getProvider(key: string): PerpsProvider | undefined {
+      return boundProviders.find((p) => p.type === key)
     },
   }
+
+  const boundProviders: PerpsProvider[] = providerPlugins.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

@@ -0,0 +1,29 @@
+import { PerpsErrorCode } from '@lifi/perps-types'
+import { PerpsError } from '../errors/PerpsError.js'
+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 function requireProvider(
+  client: PerpsSDKClient,
+  provider: string
+): PerpsProvider {
+  const plugin = client.getProvider(provider)
+  if (plugin === undefined) {
+    const error = new PerpsError(
+      PerpsErrorCode.SDKError,
+      `Provider plugin not registered: '${provider}'. Pass it to ` +
+        'createPerpsClient({ providers: [...] }).'
+    )
+    error.tool = '@lifi/perps-sdk'
+    throw error
+  }
+  return plugin
+}

package/src/errors/PerpsError.ts

@@ -1,5 +1,13 @@
 import { PerpsErrorCode } from '@lifi/perps-types'
 
+/**
+ * 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 class PerpsError extends Error {
   code: PerpsErrorCode
   override name = 'PerpsError'

package/src/errors/constants.ts

@@ -1,4 +1,10 @@
+/**
+ * Canonical human-readable messages paired with SDK-originated
+ * {@link PerpsError}s.
+ *
+ * @public
+ */
 export enum PerpsErrorMessage {
-  AgentNotFound = 'Agent not found. Call setSigningMode() first.',
-  InvalidSigningMode = 'Invalid signing mode for this operation.',
+  AgentNotFound = 'Agent not found. Complete provider setup (APPROVE_AGENT) first.',
+  AgentStorageCorrupt = 'Stored agent keypair is malformed. Revoke and re-approve the agent (APPROVE_AGENT) to regenerate it.',
 }

package/src/index.ts

@@ -1,52 +1,30 @@
-// Client
+// biome-ignore-all lint/performance/noBarrelFile: package public entry point.
+// biome-ignore-all lint/performance/noReExportAll: package public entry point.
+
+/**
+ * `@lifi/perps-sdk` — the public entry point. Exports `createPerpsClient` and
+ * `PerpsClient` (the primary API), the realtime `PerpsWsClient`, the pure
+ * calculation/parsing/order helpers, and re-exports the shared `@lifi/perps-types`.
+ *
+ * @packageDocumentation
+ * @public
+ */
 
-// Types
 export * from '@lifi/perps-types'
-// Utils
-// biome-ignore lint/correctness/useImportExtensions: package subpath export
-export { HlAbstractionMode } from '@lifi/perps-types/providers/hyperliquid'
-// Agent
-export { AgentManager } from './agent/AgentManager.js'
-export { createMemoryStorage, localStorageAdapter } from './agent/storage.js'
-export type { Agent, StorageAdapter } from './agent/types.js'
-export type {
-  PerpsBaseConfig,
-  PerpsConfig,
-  PerpsSDKClient,
-  RequestInterceptor,
-  SDKRequestOptions,
-} from './client/createPerpsClient.js'
 export {
   createPerpsClient,
   DEFAULT_API_URL,
 } from './client/createPerpsClient.js'
 export { PerpsClient } from './client/PerpsClient.js'
-export { projectAccountConfigSettings } from './client/projectAccountConfigSettings.js'
-export type {
-  CancelOrdersParams,
-  CheckPrerequisitesParams,
-  GetAccountResult,
-  GetSetupParams,
-  HyperliquidConfig,
-  ModifyOrdersParams,
-  PerpsClientOptions,
-  PlaceOrderParams as ClientPlaceOrderParams,
-  PlaceTriggerOrderParams as ClientPlaceTriggerOrderParams,
-  ProviderConfig,
-  ProviderConfigs,
-  SatisfySetupParams,
-  SatisfySetupResult,
-  SetupResult,
-} from './client/types.js'
-export { SigningMode } from './client/types.js'
-// Errors
 export { PerpsErrorMessage } from './errors/constants.js'
 export { PerpsError } from './errors/PerpsError.js'
-export { projectHyperliquidConfigSettings } from './providers/hyperliquid/accountConfig.js'
-export { projectLighterConfigSettings } from './providers/lighter/accountConfig.js'
-// Realtime
-export { PerpsWsClient } from './realtime/PerpsWsClient.js'
-export type { EventForSubscription } from './realtime/types.js'
+// Registries
+export { AssetRegistry, getAssetRegistry } from './registry/assetRegistry.js'
+export {
+  getMarketRegistry,
+  MarketRegistry,
+  toMarketDisplay,
+} from './registry/marketRegistry.js'
 // Services
 export type { CreateActionParams } from './services/createAction.js'
 export { createAction } from './services/createAction.js'
@@ -56,12 +34,15 @@ export type { GetAccountParams } from './services/getAccount.js'
 export { getAccount } from './services/getAccount.js'
 export type { GetActivityParams } from './services/getActivity.js'
 export { getActivity } from './services/getActivity.js'
-export type { GetAssetParams } from './services/getAsset.js'
-export { getAsset } from './services/getAsset.js'
 export type { GetAssetsParams } from './services/getAssets.js'
 export { getAssets } from './services/getAssets.js'
 export type { GetFillsParams } from './services/getFills.js'
 export { getFills } from './services/getFills.js'
+export type { GetMarketParams } from './services/getMarket.js'
+export { getMarket } from './services/getMarket.js'
+export type { GetMarketsParams } from './services/getMarkets.js'
+export { getMarkets } from './services/getMarkets.js'
+export { getMeta } from './services/getMeta.js'
 export type { GetOhlcvParams } from './services/getOhlcv.js'
 export { getOhlcv } from './services/getOhlcv.js'
 export type { GetOrderParams } from './services/getOrder.js'
@@ -75,43 +56,81 @@ export { getPositions } from './services/getPositions.js'
 export type { GetPricesParams } from './services/getPrices.js'
 export { getPrices } from './services/getPrices.js'
 export { getProviders } from './services/getProviders.js'
-// Signers
+export type { GetQuoteParams } from './services/getQuote.js'
+export { getQuote } from './services/getQuote.js'
+export { getTermsAcceptance } from './services/getTermsAcceptance.js'
+export { resolveQuote, resolveQuoteMarket } from './services/resolveQuote.js'
+export {
+  QUOTE_THROTTLE_MS,
+  resolveSubscribeQuote,
+} from './services/resolveSubscribeQuote.js'
+export {
+  parseStoredRecord,
+  readValidatedRecord,
+} from './storage/parseStoredRecord.js'
+export { createMemoryStorage, localStorageAdapter } from './storage/storage.js'
+export type { StorageAdapter } from './storage/types.js'
+export type { FetchWithRetryOptions } from './transport/fetchWithRetry.js'
+export { fetchWithRetry } from './transport/fetchWithRetry.js'
 export type {
-  ApiKeyPair,
-  ApproveReadOnlyTokenInputs,
-  ApproveReadOnlyTokenResult,
-  ChangePubKeyResult,
-  LighterApiKey,
-  LighterCreateTokenResponse,
-  LighterReadOnlyToken,
-  LighterReadOnlyTokenManagerOptions,
-  LighterSignedBlob,
-  LighterSignerConfig,
-  LighterSignerContext,
-  LighterTokenFetcher,
-  LighterWalletSigner,
-  LighterWasmExports,
-  LoadLighterWasmOptions,
-} from './signers/lighter/index.js'
+  ProviderRetryConfig,
+  ResolvedRetryPolicy,
+  RetryAttemptContext,
+  RetryClassification,
+  RetryClassifyContext,
+  RetryConfig,
+  RetryPolicy,
+} from './transport/retryPolicy.js'
 export {
-  buildReadOnlyTokenMessage,
-  DEFAULT_API_KEY_INDEX,
-  DEFAULT_LIGHTER_API_URL,
-  DEFAULT_READ_ONLY_TOKEN_NAME,
-  defaultLighterTokenFetcher,
-  LIGHTER_PROVIDER_KEY,
-  LighterKeyStore,
-  LighterReadOnlyTokenManager,
-  LighterSigner,
-  loadLighterWasm,
-  resetLighterWasmCache,
-  walletClientSigner,
-} from './signers/lighter/index.js'
-export type { AccountSummary } from './utils/accountSummary.js'
-export { calculateAccountSummary } from './utils/accountSummary.js'
+  DISABLED_RETRY,
+  LIFI_REQUEST_KEY,
+  LIFI_RETRY_DEFAULTS,
+  resolveRetryPolicy,
+} from './transport/retryPolicy.js'
+export type {
+  BuildProviderSetupParams,
+  CancelOrdersParams,
+  ExecuteProviderSetupParams,
+  ExecuteProviderSetupResult,
+  GetAccountResult,
+  GetSetupParams,
+  ModifyOrdersParams,
+  PerpsClientOptions,
+  PerpsConfig,
+  PlaceOrderParams as ClientPlaceOrderParams,
+  PlaceTriggerOrderParams as ClientPlaceTriggerOrderParams,
+  ProviderSetup,
+} from './types/api.js'
+export type {
+  HyperliquidConfig,
+  PerpsBaseConfig,
+  PerpsClientSigner,
+  ProviderConfig,
+  ProviderConfigs,
+  RequestInterceptor,
+  SDKRequestOptions,
+} from './types/config.js'
+export type {
+  ActionSignerContribution,
+  LiquidationEstimateParams,
+  PerpsProvider,
+  PerpsProviderPlugin,
+  PerpsSDKClient,
+  ProviderGetAccountParams,
+  ProviderGetActivityParams,
+  ProviderGetFillsParams,
+  ProviderGetOrderParams,
+  ProviderGetOrdersParams,
+  ProviderGetPositionsParams,
+  ProviderGetQuoteParams,
+  QuoteListener,
+  SignActionsContext,
+} from './types/provider.js'
+export { summarizeAccount } from './utils/accountSummary.js'
 export type { ExpectedPnl } from './utils/calculations.js'
 export {
   applySlippage,
+  buildQuote,
   calculateExpectedPnl,
   calculateNotionalValue,
   calculatePositionSize,
@@ -119,20 +138,34 @@ export {
   calculateRequiredMargin,
   calculateRoe,
   calculateUnrealizedPnl,
+  effectiveLeverage,
   estimateFees,
+  liquidationDistancePercent,
   percentFromPrice,
   priceFromPercent,
+  removableMargin,
+  walkOrderbook,
 } from './utils/calculations.js'
+export type { DepositProviderKey } from './utils/depositChain.js'
+export {
+  LIFI_DEPOSIT_CHAIN_BY_PROVIDER,
+  lifiDepositChainForProvider,
+} from './utils/depositChain.js'
+export { ExplorerChainId, explorerTxUrl } from './utils/explorer.js'
+export { classifyFillFromPosition } from './utils/fillClassification.js'
+export type { FormatOptions } from './utils/format.js'
 export {
-  calculateLiquidationPrice,
-  calculateMaintenanceMarginRate,
-  formatOrderPrice,
-  formatOrderSize,
-  getMaxPriceDecimals,
-} from './utils/hyperliquid/index.js'
+  formatCompactUsd,
+  formatPrice,
+  formatSignedPercent,
+  formatSignedUsd,
+  formatUsd,
+} from './utils/format.js'
 export {
+  ACTIVE_ORDER_STATUSES,
   classifyFill,
   FillClassification,
+  isActiveOrderStatus,
   isStopLossOrder,
   isTakeProfitOrder,
   isTpSlOrder,
@@ -146,14 +179,37 @@ export {
 export { stringToFloat } from './utils/parse.js'
 export {
   directionSign,
+  estimateIsolatedLiquidationPrice,
   predictAverageEntryPrice,
   predictNewLeverage,
   predictUnrealizedPnl,
   realizedPnlOnClose,
 } from './utils/positionMath.js'
-export { signTypedData } from './utils/signTypedData.js'
+export {
+  signTypedData,
+  signTypedDataWithSigner,
+} from './utils/signTypedData.js'
 export { fromBaseUnits, fromBaseUnitsNumber } from './utils/units.js'
 export { validateMargin } from './utils/validation.js'
-
 // Version
 export { name, version } from './version.js'
+export { cachePromise } from './websocket/cachePromise.js'
+export type {
+  PerpsWsClientOptions,
+  WsProviderFactory,
+} from './websocket/PerpsWsClient.js'
+export { PerpsWsClient } from './websocket/PerpsWsClient.js'
+export type { ReconnectingWebSocketOptions } from './websocket/ReconnectingWebSocket.js'
+export { ReconnectingWebSocket } from './websocket/ReconnectingWebSocket.js'
+export type {
+  EventForSubscription,
+  SubscriptionListener,
+  WsConnectionStatus,
+  WsProvider,
+  WsStatusListener,
+} from './websocket/types.js'
+export {
+  WS_CHANNEL_TEARDOWN_LINGER_MS,
+  WsProviderBase,
+} from './websocket/WsProviderBase.js'
+export { wsLog } from './websocket/wsLog.js'

package/src/registry/assetRegistry.ts

@@ -0,0 +1,62 @@
+import type { Asset, AssetsResponse } from '@lifi/perps-types'
+import { buildUrl, request } from '../transport/request.js'
+import type { PerpsSDKClient } from '../types/provider.js'
+import { ReferenceDataRegistry } from './referenceDataRegistry.js'
+
+/**
+ * Per-provider index over the backend's `/assets` token registry, keyed by
+ * `Asset.id` — the provider-native asset id (Lighter: the stringified
+ * `asset_id`, Hyperliquid spot: the venue token index). Obtain via
+ * {@link getAssetRegistry}.
+ *
+ * @public
+ */
+export class AssetRegistry extends ReferenceDataRegistry<Asset> {
+  constructor(client: PerpsSDKClient, provider: string) {
+    super(client, provider, 'asset')
+  }
+
+  /** The most recently synced asset list. Empty before the first {@link sync}. */
+  get assets(): readonly Asset[] {
+    return this.items
+  }
+
+  protected fetchItems(bypassHttpCache: boolean): Promise<Asset[]> {
+    const url = buildUrl(`${this.client.config.apiUrl}/assets`, {
+      provider: this.provider,
+    })
+    return request<AssetsResponse>(
+      this.client.config,
+      url,
+      bypassHttpCache ? { cache: 'no-cache' } : {}
+    ).then((response) => response.assets)
+  }
+
+  protected keyOf(asset: Asset): string {
+    return asset.id
+  }
+}
+
+const registries = new WeakMap<PerpsSDKClient, Map<string, AssetRegistry>>()
+
+/**
+ * The stable {@link AssetRegistry} for `(client, provider)`.
+ *
+ * @public
+ */
+export function getAssetRegistry(
+  client: PerpsSDKClient,
+  provider: string
+): AssetRegistry {
+  let byProvider = registries.get(client)
+  if (byProvider === undefined) {
+    byProvider = new Map()
+    registries.set(client, byProvider)
+  }
+  let registry = byProvider.get(provider)
+  if (registry === undefined) {
+    registry = new AssetRegistry(client, provider)
+    byProvider.set(provider, registry)
+  }
+  return registry
+}