@lifi/perps-sdk 0.0.0-preview-64fca0d

package/src/client/createPerpsClient.ts

@@ -0,0 +1,100 @@
+import { PerpsErrorCode } from '@lifi/perps-types'
+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'
+
+/**
+ * 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(
+      PerpsErrorCode.SDKError,
+      'Integrator is required. Please see documentation at https://docs.li.fi'
+    )
+    error.tool = '@lifi/perps-sdk'
+    throw error
+  }
+
+  const apiUrl = options.apiUrl ?? DEFAULT_API_URL
+  const { providerPlugins, providerConfigs } = splitProviders(options.providers)
+
+  const config: PerpsBaseConfig = {
+    integrator: options.integrator,
+    apiKey: options.apiKey,
+    apiUrl,
+    disableVersionCheck: options.disableVersionCheck,
+    requestInterceptor: options.requestInterceptor,
+    providers: providerConfigs,
+    retry: options.retry,
+    fetch: options.fetch,
+  }
+
+  const client: PerpsSDKClient = {
+    get config() {
+      return config
+    },
+    get userWallet() {
+      return options.userWallet
+    },
+    get providers() {
+      return boundProviders
+    },
+    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

@@ -0,0 +1,23 @@
+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'
+  tool?: string
+
+  constructor(
+    code: PerpsErrorCode = PerpsErrorCode.DefaultError,
+    message = 'Unknown error occurred'
+  ) {
+    super(message)
+    this.code = code
+  }
+}

package/src/errors/constants.ts

@@ -0,0 +1,10 @@
+/**
+ * Canonical human-readable messages paired with SDK-originated
+ * {@link PerpsError}s.
+ *
+ * @public
+ */
+export enum PerpsErrorMessage {
+  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

@@ -0,0 +1,215 @@
+// 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
+ */
+
+export * from '@lifi/perps-types'
+export {
+  createPerpsClient,
+  DEFAULT_API_URL,
+} from './client/createPerpsClient.js'
+export { PerpsClient } from './client/PerpsClient.js'
+export { PerpsErrorMessage } from './errors/constants.js'
+export { PerpsError } from './errors/PerpsError.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'
+export type { ExecuteActionParams } from './services/executeAction.js'
+export { executeAction } from './services/executeAction.js'
+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 { 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'
+export { getOrder } from './services/getOrder.js'
+export type { GetOrderbookParams } from './services/getOrderbook.js'
+export { getOrderbook } from './services/getOrderbook.js'
+export type { GetOrdersParams } from './services/getOrders.js'
+export { getOrders } from './services/getOrders.js'
+export type { GetPositionsParams } from './services/getPositions.js'
+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'
+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 {
+  ProviderRetryConfig,
+  ResolvedRetryPolicy,
+  RetryAttemptContext,
+  RetryClassification,
+  RetryClassifyContext,
+  RetryConfig,
+  RetryPolicy,
+} from './transport/retryPolicy.js'
+export {
+  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,
+  calculateRealizedPnlPercent,
+  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 {
+  formatCompactUsd,
+  formatPrice,
+  formatSignedPercent,
+  formatSignedUsd,
+  formatUsd,
+} from './utils/format.js'
+export {
+  ACTIVE_ORDER_STATUSES,
+  classifyFill,
+  FillClassification,
+  isActiveOrderStatus,
+  isStopLossOrder,
+  isTakeProfitOrder,
+  isTpSlOrder,
+} from './utils/orderClassification.js'
+export {
+  expectedRealizedPnlForOpenOrder,
+  expectedRealizedPnlForTriggerOrder,
+  findMatchingPosition,
+  resolveCloseSize,
+} from './utils/orderMath.js'
+export { stringToFloat } from './utils/parse.js'
+export {
+  directionSign,
+  estimateIsolatedLiquidationPrice,
+  predictAverageEntryPrice,
+  predictNewLeverage,
+  predictUnrealizedPnl,
+  realizedPnlOnClose,
+} from './utils/positionMath.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
+}

package/src/registry/marketRegistry.ts

@@ -0,0 +1,100 @@
+import type { Market, MarketDisplay, MarketsResponse } from '@lifi/perps-types'
+import { PerpsErrorCode } from '@lifi/perps-types'
+import { PerpsError } from '../errors/PerpsError.js'
+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 enriched `/markets` list, keyed by
+ * `Market.id` — the venue wire key (Hyperliquid: the coin string, Lighter:
+ * the stringified `market_index`). Obtain via {@link getMarketRegistry};
+ * shared by the provider packages' REST services and WS providers.
+ *
+ * @public
+ */
+export class MarketRegistry extends ReferenceDataRegistry<Market> {
+  constructor(client: PerpsSDKClient, provider: string) {
+    super(client, provider, 'market')
+  }
+
+  /** The most recently synced market list. Empty before the first {@link sync}. */
+  get markets(): readonly Market[] {
+    return this.items
+  }
+
+  /**
+   * Lookup by `Market.id`, throwing when the backend list does not know the
+   * id. The list is the source of truth for every tradable market, so an id
+   * the venue references but the backend does not know is a hard error —
+   * never a silent fallback to an unenriched stand-in.
+   *
+   * @throws {PerpsError} `MarketNotFound`.
+   */
+  require(marketId: string): Market {
+    const market = this.get(marketId)
+    if (market === undefined) {
+      const error = new PerpsError(
+        PerpsErrorCode.MarketNotFound,
+        `No ${this.provider} market found for marketId '${marketId}'`
+      )
+      error.tool = this.provider
+      throw error
+    }
+    return market
+  }
+
+  protected fetchItems(bypassHttpCache: boolean): Promise<Market[]> {
+    const url = buildUrl(`${this.client.config.apiUrl}/markets`, {
+      provider: this.provider,
+    })
+    return request<MarketsResponse>(
+      this.client.config,
+      url,
+      bypassHttpCache ? { cache: 'no-cache' } : {}
+    ).then((response) => response.markets)
+  }
+
+  protected keyOf(market: Market): string {
+    return market.id
+  }
+}
+
+const registries = new WeakMap<PerpsSDKClient, Map<string, MarketRegistry>>()
+
+/**
+ * The stable {@link MarketRegistry} for `(client, provider)`.
+ *
+ * @public
+ */
+export function getMarketRegistry(
+  client: PerpsSDKClient,
+  provider: string
+): MarketRegistry {
+  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 MarketRegistry(client, provider)
+    byProvider.set(provider, registry)
+  }
+  return registry
+}
+
+/**
+ * Project a {@link Market} to the {@link MarketDisplay} identity embedded on
+ * mapped positions/orders/fills, preserving the backend's `baseAsset` and
+ * `quoteAsset` verbatim (logos, display names).
+ *
+ * @public
+ */
+export const toMarketDisplay = (market: Market): MarketDisplay => ({
+  providerId: market.providerId,
+  id: market.id,
+  categoryId: market.categoryId,
+  baseAsset: market.baseAsset,
+  quoteAsset: market.quoteAsset,
+})

package/src/registry/referenceDataRegistry.ts

@@ -0,0 +1,95 @@
+import type { PerpsSDKClient } from '../types/provider.js'
+
+/** Minimum gap between unknown-id-triggered, HTTP-cache-bypassing refetches. */
+const REFRESH_COOLDOWN_MS = 60_000
+
+/**
+ * Per-provider hash index over one of the provider's reference-data lists
+ * (`/markets`, `/assets`), keyed by the list's own primary key.
+ *
+ * NOT a cache: it holds no freshness policy of its own. Every {@link sync}
+ * refetches through the HTTP layer, whose `cache-control` headers decide
+ * whether the response comes from disk or the network. A lookup miss
+ * schedules a cooldown-gated background refetch that bypasses the HTTP
+ * cache — the id may have listed after the cached snapshot.
+ *
+ * @internal
+ */
+export abstract class ReferenceDataRegistry<T> {
+  private index = new Map<string, T>()
+  private current: readonly T[] = []
+  private inflight: Promise<readonly T[]> | undefined
+  private warnedIds = new Set<string>()
+  private refreshAfter = 0
+
+  protected constructor(
+    protected readonly client: PerpsSDKClient,
+    readonly provider: string,
+    private readonly kind: string
+  ) {}
+
+  /** Fetch the provider's full list, bypassing the HTTP cache when asked. */
+  protected abstract fetchItems(bypassHttpCache: boolean): Promise<T[]>
+
+  /** The item's primary key — what {@link get} is keyed by. */
+  protected abstract keyOf(item: T): string
+
+  /**
+   * Fetch the list through the HTTP cache and rebuild the index. Concurrent
+   * callers share one in-flight fetch; a settled fetch is never reused, so
+   * HTTP `cache-control` alone governs freshness.
+   */
+  sync(): Promise<readonly T[]> {
+    if (!this.inflight) {
+      this.inflight = this.load(false).finally(() => {
+        this.inflight = undefined
+      })
+    }
+    return this.inflight
+  }
+
+  /** The most recently synced list. Empty before the first {@link sync}. */
+  protected get items(): readonly T[] {
+    return this.current
+  }
+
+  /**
+   * O(1) lookup by primary key. A miss warns once per id and schedules the
+   * cooldown-gated, cache-bypassing background refetch.
+   */
+  get(id: string): T | undefined {
+    const item = this.index.get(id)
+    if (item !== undefined) {
+      return item
+    }
+    if (!this.warnedIds.has(id)) {
+      this.warnedIds.add(id)
+      console.warn(`[${this.provider}] unknown ${this.kind} id '${id}'`)
+    }
+    this.scheduleRefresh()
+    return undefined
+  }
+
+  private async load(bypassHttpCache: boolean): Promise<readonly T[]> {
+    const items = await this.fetchItems(bypassHttpCache)
+    this.index = new Map(items.map((item) => [this.keyOf(item), item]))
+    this.current = items
+    this.warnedIds.clear()
+    return items
+  }
+
+  private scheduleRefresh(): void {
+    const now = Date.now()
+    if (now < this.refreshAfter) {
+      return
+    }
+    // Set before any await so concurrent misses cannot trigger a refetch storm.
+    this.refreshAfter = now + REFRESH_COOLDOWN_MS
+    this.load(true).catch((error) =>
+      console.error(
+        `[${this.provider}] ${this.kind} registry refresh failed`,
+        error
+      )
+    )
+  }
+}

package/src/services/createAction.ts

@@ -0,0 +1,52 @@
+import type {
+  ActionParamsMap,
+  ActionType,
+  CreateActionResponse,
+} from '@lifi/perps-types'
+import type { Address } from 'viem'
+import { request } from '../transport/request.js'
+import type { SDKRequestOptions } from '../types/config.js'
+import type { PerpsSDKClient } from '../types/provider.js'
+
+/**
+ * Parameters for {@link createAction}.
+ *
+ * @public
+ */
+export interface CreateActionParams<T extends ActionType = ActionType> {
+  provider: string
+  address: Address
+  signerAddress?: Address
+  action: T
+  params: ActionParamsMap[T]
+}
+
+/**
+ * Request the backend to build the unsigned `ActionStep`s for an action. The
+ * returned steps are signed client-side and submitted via
+ * {@link executeAction}.
+ *
+ * @throws {PerpsError} On backend error responses, network, or parsing errors.
+ * @public
+ */
+export async function createAction<T extends ActionType>(
+  client: PerpsSDKClient,
+  params: CreateActionParams<T>,
+  options?: SDKRequestOptions
+): Promise<CreateActionResponse> {
+  return request<CreateActionResponse>(
+    client.config,
+    `${client.config.apiUrl}/createAction`,
+    {
+      method: 'POST',
+      body: JSON.stringify({
+        provider: params.provider,
+        address: params.address,
+        signerAddress: params.signerAddress,
+        action: params.action,
+        params: params.params,
+      }),
+    },
+    options
+  )
+}