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

package/src/services/getQuote.ts

@@ -0,0 +1,58 @@
+import type { Quote, QuoteSide, TradeType } from '@lifi/perps-types'
+import { requireProvider } from '../client/requireProvider.js'
+import type { SDKRequestOptions } from '../types/config.js'
+import type { PerpsSDKClient } from '../types/provider.js'
+
+/**
+ * Parameters for {@link getQuote}.
+ *
+ * @public
+ */
+export interface GetQuoteParams {
+  provider: string
+  /** Human `displaySymbol`, e.g. `"BTC"`. */
+  symbol: string
+  side: QuoteSide
+  /** USD notional to fill. */
+  size: number
+  type: TradeType
+}
+
+/**
+ * Get a one-shot fill quote for `size` USD notional of `symbol` on a single
+ * venue: VWAP expected fill, price impact (bps), base-tier taker fee, and
+ * funding (perps only). Delegates to the registered venue plugin, which
+ * resolves the symbol against its own markets (scoped by `type`) and walks its
+ * orderbook. Cross-venue comparison is a consumer-side loop over
+ * `client.providers`.
+ *
+ * @throws {PerpsError} When the provider plugin is not registered, no market
+ *   matches the symbol+type, or on network / parsing errors.
+ * @example
+ * ```ts
+ * const quote = await getQuote(client, {
+ *   provider: 'hyperliquid',
+ *   symbol: 'BTC',
+ *   side: 'buy',
+ *   size: 10_000,
+ *   type: 'perps',
+ * })
+ * console.log(quote.expectedFillPrice, quote.priceImpactBps)
+ * ```
+ * @public
+ */
+export async function getQuote(
+  client: PerpsSDKClient,
+  params: GetQuoteParams,
+  options?: SDKRequestOptions
+): Promise<Quote> {
+  return requireProvider(client, params.provider).getQuote(
+    {
+      symbol: params.symbol,
+      side: params.side,
+      size: params.size,
+      type: params.type,
+    },
+    options
+  )
+}

package/src/services/getTermsAcceptance.ts

@@ -0,0 +1,34 @@
+import type { TermsAcceptanceStatus } from '@lifi/perps-types'
+import type { Address } from 'viem'
+import { buildUrl, request } from '../transport/request.js'
+import type { SDKRequestOptions } from '../types/config.js'
+import type { PerpsSDKClient } from '../types/provider.js'
+
+/**
+ * Get the current Terms of Service (version + full content) and whether the
+ * given address has accepted them. Provider-independent — reads from the
+ * platform `meta` surface, not a venue plugin.
+ *
+ * @param client - The SDK client instance
+ * @param address - Address whose acceptance status to resolve
+ * @param options - Request options (e.g., AbortSignal)
+ * @throws {PerpsError} On backend error responses, network, or parsing errors.
+ *
+ * @example
+ * ```ts
+ * const client = createPerpsClient({ integrator: 'my-app' })
+ * const terms = await getTermsAcceptance(client, '0x1234...')
+ * if (!terms.accepted) {
+ *   // prompt the user to accept terms.content (version terms.termsVersion)
+ * }
+ * ```
+ * @public
+ */
+export async function getTermsAcceptance(
+  client: PerpsSDKClient,
+  address: Address,
+  options?: SDKRequestOptions
+): Promise<TermsAcceptanceStatus> {
+  const url = buildUrl(`${client.config.apiUrl}/meta/terms`, { address })
+  return request<TermsAcceptanceStatus>(client.config, url, {}, options)
+}

package/src/services/resolveQuote.ts

@@ -0,0 +1,90 @@
+import {
+  type FeeTier,
+  type Market,
+  PerpsErrorCode,
+  type Quote,
+} from '@lifi/perps-types'
+import { PerpsError } from '../errors/PerpsError.js'
+import type { SDKRequestOptions } from '../types/config.js'
+import type {
+  PerpsSDKClient,
+  ProviderGetQuoteParams,
+} from '../types/provider.js'
+import { buildQuote } from '../utils/calculations.js'
+import { getMarkets } from './getMarkets.js'
+import { getOrderbook } from './getOrderbook.js'
+
+/**
+ * Shared provider-side `getQuote` implementation: resolve `params.symbol` to a
+ * market on `provider` (matching `baseAsset.displaySymbol`, scoped by
+ * `params.type`), fetch the orderbook snapshot, and build the {@link Quote}
+ * with the provider's public base `feeTier`. Both venue plugins delegate here
+ * so symbol resolution and the book walk live in one place; each plugin only
+ * supplies its own base tier.
+ *
+ * @throws {PerpsError} `MarketNotFound` when no market matches symbol+type.
+ * @internal
+ */
+export async function resolveQuote(
+  client: PerpsSDKClient,
+  provider: string,
+  params: ProviderGetQuoteParams,
+  feeTier: FeeTier,
+  options?: SDKRequestOptions
+): Promise<Quote> {
+  const market = await resolveQuoteMarket(client, provider, params, options)
+
+  const { bids, asks } = await getOrderbook(
+    client,
+    { provider, marketId: market.id },
+    options
+  )
+
+  return buildQuote({
+    provider,
+    symbol: params.symbol,
+    type: params.type,
+    side: params.side,
+    sizeUsd: params.size,
+    market,
+    bids,
+    asks,
+    feeTier,
+    timestamp: Date.now(),
+  })
+}
+
+/**
+ * Resolve `params.symbol` to a market on `provider` (matching
+ * `baseAsset.displaySymbol`, scoped by `params.type`). Shared by the one-shot
+ * {@link resolveQuote} and the streaming quote subscription so both quote the
+ * same market for a given symbol+type.
+ *
+ * @throws {PerpsError} `MarketNotFound` when no market matches symbol+type.
+ * @internal
+ */
+export async function resolveQuoteMarket(
+  client: PerpsSDKClient,
+  provider: string,
+  params: Pick<ProviderGetQuoteParams, 'symbol' | 'type'>,
+  options?: SDKRequestOptions
+): Promise<Market> {
+  const { markets } = await getMarkets(client, { provider }, options)
+  const market = markets.find(
+    (m) =>
+      m.baseAsset.displaySymbol === params.symbol &&
+      isMarketOfType(m, params.type)
+  )
+  if (market === undefined) {
+    throw new PerpsError(
+      PerpsErrorCode.MarketNotFound,
+      `No ${params.type} market found on '${provider}' for symbol '${params.symbol}'.`
+    )
+  }
+  return market
+}
+
+const isMarketOfType = (
+  market: Market,
+  type: ProviderGetQuoteParams['type']
+): boolean => ('funding' in market ? type === 'perps' : type === 'spot')

package/src/services/resolveSubscribeQuote.ts

@@ -0,0 +1,107 @@
+import type { FeeTier, OrderbookResponse } from '@lifi/perps-types'
+import type {
+  PerpsSDKClient,
+  ProviderGetQuoteParams,
+  QuoteListener,
+} from '../types/provider.js'
+import { buildQuote } from '../utils/calculations.js'
+import type { WsProvider } from '../websocket/types.js'
+import { resolveQuoteMarket } from './resolveQuote.js'
+
+/**
+ * Minimum gap between successive streamed {@link Quote} emissions — the same
+ * 100 ms pacing applied to streamed orderbook rendering, so a quote ticks no
+ * faster than the book it derives from.
+ *
+ * @public
+ */
+export const QUOTE_THROTTLE_MS = 100
+
+/**
+ * Shared provider-side `subscribeQuote` implementation: resolve
+ * `params.symbol` to a market on `provider` (via {@link resolveQuoteMarket}),
+ * subscribe to that market's orderbook channel on `ws`, and on each book
+ * update rebuild the {@link Quote} with the provider's public base `feeTier` —
+ * the same transform the one-shot `resolveQuote` applies to a REST snapshot.
+ * Emissions are throttled to {@link QUOTE_THROTTLE_MS}: the first book update
+ * emits immediately, then at most one (trailing, latest-book) emission per
+ * interval. Both venue WS plugins delegate here; each only supplies its own
+ * base tier.
+ *
+ * The returned unsubscribe is idempotent — it releases the underlying
+ * orderbook listener once and cancels any pending trailing emission, so the
+ * wire subscription's ref count cannot be double-decremented.
+ *
+ * @throws {PerpsError} `MarketNotFound` when no market matches symbol+type.
+ * @internal
+ */
+export async function resolveSubscribeQuote(
+  client: PerpsSDKClient,
+  provider: string,
+  ws: Pick<WsProvider, 'subscribe'>,
+  params: ProviderGetQuoteParams,
+  feeTier: FeeTier,
+  onQuote: QuoteListener
+): Promise<() => void> {
+  const market = await resolveQuoteMarket(client, provider, params)
+
+  let latestBook: OrderbookResponse | undefined
+  let lastEmitAt = Number.NEGATIVE_INFINITY
+  let trailing: ReturnType<typeof setTimeout> | undefined
+
+  const emit = () => {
+    if (latestBook === undefined) {
+      return
+    }
+    lastEmitAt = Date.now()
+    onQuote(
+      buildQuote({
+        provider,
+        symbol: params.symbol,
+        type: params.type,
+        side: params.side,
+        sizeUsd: params.size,
+        market,
+        bids: latestBook.bids,
+        asks: latestBook.asks,
+        feeTier,
+        timestamp: Date.now(),
+      })
+    )
+  }
+
+  const unsubscribe = await ws.subscribe(
+    { channel: 'orderbook', dex: provider, marketId: market.id },
+    (event) => {
+      if (event.channel !== 'orderbook') {
+        return
+      }
+      latestBook = event.data
+      if (trailing !== undefined) {
+        return
+      }
+      const wait = QUOTE_THROTTLE_MS - (Date.now() - lastEmitAt)
+      if (wait <= 0) {
+        emit()
+      } else {
+        trailing = setTimeout(() => {
+          trailing = undefined
+          emit()
+        }, wait)
+      }
+    }
+  )
+
+  let released = false
+  return () => {
+    if (released) {
+      return
+    }
+    released = true
+    if (trailing !== undefined) {
+      clearTimeout(trailing)
+      trailing = undefined
+    }
+    unsubscribe()
+  }
+}

package/src/storage/parseStoredRecord.ts

@@ -0,0 +1,55 @@
+import type { StorageAdapter } from './types.js'
+
+/**
+ * Parse a persisted (browser-writable) JSON record and validate it against a
+ * caller-supplied shape guard. localStorage is user-writable, so a stored value
+ * may be truncated, hand-edited, or written by an older schema; `JSON.parse(...)
+ * as T` would type-check such a record yet carry missing/invalid fields that
+ * fail far from here.
+ *
+ * Returns the parsed value when `isValid` accepts it; returns `null` when the
+ * record is absent, unparseable, or fails validation (i.e. poisoned). A `null`
+ * result is the "malformed-or-absent" signal — callers decide whether that
+ * means "regenerate deliberately" or "surface an error", but they never get a
+ * structurally-invalid `T`.
+ *
+ * @param raw Stored string, or `null` when the key is absent.
+ * @param isValid Shape guard run against the parsed value.
+ */
+export function parseStoredRecord<T>(
+  raw: string | null,
+  isValid: (value: unknown) => value is T
+): T | null {
+  if (raw === null) {
+    return null
+  }
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    return null
+  }
+  return isValid(parsed) ? parsed : null
+}
+
+/**
+ * Read and validate a persisted record in one step, evicting the key when the
+ * stored value is present but poisoned (unparseable or failing `isValid`) so a
+ * later read does not keep tripping over the same corrupt entry.
+ *
+ * Returns `null` for both the genuine-absence and the evicted-poison cases;
+ * callers that must distinguish them should compare against the pre-read
+ * presence of the key themselves.
+ */
+export async function readValidatedRecord<T>(
+  storage: StorageAdapter,
+  key: string,
+  isValid: (value: unknown) => value is T
+): Promise<T | null> {
+  const raw = await storage.get(key)
+  const parsed = parseStoredRecord(raw, isValid)
+  if (parsed === null && raw !== null) {
+    await storage.remove(key)
+  }
+  return parsed
+}

package/src/storage/storage.ts

@@ -0,0 +1,60 @@
+import type { StorageAdapter } from './types.js'
+
+/**
+ * localStorage adapter for browser environments. Falls back to a no-op when
+ * `localStorage` is unavailable (e.g. SSR).
+ *
+ * @public
+ */
+export const localStorageAdapter: StorageAdapter = {
+  get: (key: string): Promise<string | null> => {
+    try {
+      return Promise.resolve(localStorage.getItem(key))
+    } catch {
+      return Promise.resolve(null)
+    }
+  },
+
+  set: (key: string, value: string): Promise<void> => {
+    try {
+      localStorage.setItem(key, value)
+    } catch {
+      // localStorage not available
+    }
+    return Promise.resolve()
+  },
+
+  remove: (key: string): Promise<void> => {
+    try {
+      localStorage.removeItem(key)
+    } catch {
+      // localStorage not available
+    }
+    return Promise.resolve()
+  },
+}
+
+/**
+ * In-memory storage adapter for testing or server-side use.
+ *
+ * @public
+ */
+export function createMemoryStorage(): StorageAdapter {
+  const store = new Map<string, string>()
+
+  return {
+    get: (key: string): Promise<string | null> => {
+      return Promise.resolve(store.get(key) ?? null)
+    },
+
+    set: (key: string, value: string): Promise<void> => {
+      store.set(key, value)
+      return Promise.resolve()
+    },
+
+    remove: (key: string): Promise<void> => {
+      store.delete(key)
+      return Promise.resolve()
+    },
+  }
+}

package/src/storage/types.ts

@@ -0,0 +1,13 @@
+/**
+ * Storage adapter interface for persisting SDK session credentials (provider
+ * agent keypairs, API keys, read-only tokens). Implement this to use custom
+ * storage (e.g. encrypted storage, a database, async key-value stores).
+ */
+export interface StorageAdapter {
+  /** Get a value by key. */
+  get(key: string): Promise<string | null>
+  /** Set a value by key. */
+  set(key: string, value: string): Promise<void>
+  /** Remove a value by key. */
+  remove(key: string): Promise<void>
+}

package/src/transport/fetchWithRetry.ts

@@ -0,0 +1,116 @@
+import { sleep } from '../utils/sleep.js'
+import type { ResolvedRetryPolicy, RetryClassification } from './retryPolicy.js'
+
+/**
+ * Options for {@link fetchWithRetry}.
+ *
+ * @public
+ */
+export interface FetchWithRetryOptions {
+  policy: ResolvedRetryPolicy
+  fetchImpl?: typeof fetch
+  signal?: AbortSignal
+}
+
+/**
+ * Wrap `fetch` with policy-driven retry. Honors `Retry-After` (when present
+ * and `respectRetryAfter` is true), otherwise falls back to exponential
+ * backoff with full jitter, capped by `maxDelayMs`. Network errors (thrown
+ * `fetch` rejections) are treated as `retry-network` — same retry budget as
+ * 5xx. An aborted signal short-circuits without further attempts.
+ *
+ * @public
+ */
+export async function fetchWithRetry(
+  input: RequestInfo | URL,
+  init: RequestInit | undefined,
+  options: FetchWithRetryOptions
+): Promise<Response> {
+  const { policy, fetchImpl = fetch, signal } = options
+  const mergedInit: RequestInit = signal ? { ...init, signal } : (init ?? {})
+
+  let attempt = 0
+  while (true) {
+    if (signal?.aborted) {
+      throw signal.reason ?? new DOMException('Aborted', 'AbortError')
+    }
+
+    let response: Response | undefined
+    let networkError: unknown
+    try {
+      response = await fetchImpl(input, mergedInit)
+    } catch (error) {
+      networkError = error
+    }
+
+    if (response?.ok) {
+      return response
+    }
+
+    const classification: RetryClassification = response
+      ? policy.classify({ response })
+      : 'retry-network'
+
+    const attemptsRemaining = policy.maxAttempts - attempt - 1
+    const isRetriable = classification !== 'fail' && attemptsRemaining > 0
+
+    if (!isRetriable) {
+      if (response) {
+        return response
+      }
+      throw networkError
+    }
+
+    if (policy.shouldRetry) {
+      const ok = await policy.shouldRetry({
+        attempt,
+        response,
+        error: networkError,
+        classification,
+      })
+      if (!ok) {
+        if (response) {
+          return response
+        }
+        throw networkError
+      }
+    }
+
+    const delayMs = computeDelay(policy, attempt, response)
+    if (delayMs > 0) {
+      await sleep(delayMs)
+    }
+    attempt++
+  }
+}
+
+function computeDelay(
+  policy: ResolvedRetryPolicy,
+  attempt: number,
+  response: Response | undefined
+): number {
+  if (policy.respectRetryAfter && response) {
+    const header = response.headers.get('Retry-After')
+    if (header) {
+      const parsed = parseRetryAfter(header)
+      if (parsed !== undefined) {
+        return Math.min(parsed, policy.maxDelayMs)
+      }
+    }
+  }
+  const exp = policy.baseDelayMs * 2 ** attempt
+  const capped = Math.min(exp, policy.maxDelayMs)
+  return Math.floor(Math.random() * capped)
+}
+
+function parseRetryAfter(header: string): number | undefined {
+  const seconds = Number(header)
+  if (Number.isFinite(seconds) && seconds >= 0) {
+    return seconds * 1000
+  }
+  const dateMs = Date.parse(header)
+  if (!Number.isNaN(dateMs)) {
+    return Math.max(0, dateMs - Date.now())
+  }
+  return undefined
+}

package/src/transport/request.ts

@@ -0,0 +1,123 @@
+import type { PerpsErrorBody } from '@lifi/perps-types'
+import { PerpsErrorCode } from '@lifi/perps-types'
+import { PerpsError } from '../errors/PerpsError.js'
+import type { PerpsBaseConfig, SDKRequestOptions } from '../types/config.js'
+import { version } from '../version.js'
+import { fetchWithRetry } from './fetchWithRetry.js'
+import {
+  LIFI_REQUEST_KEY,
+  LIFI_RETRY_DEFAULTS,
+  type RetryPolicy,
+  resolveRetryPolicy,
+} from './retryPolicy.js'
+
+/**
+ * `RequestInit` plus a per-call retry override.
+ *
+ * @internal
+ */
+export interface RequestOptions extends RequestInit {
+  /** Per-call retry override. Falls back to the resolved client-level policy. */
+  retry?: RetryPolicy | false
+}
+
+/**
+ * Internal HTTP helper: applies SDK headers, retry policy, and the request
+ * interceptor, then normalizes failures into {@link PerpsError}.
+ *
+ * @internal
+ */
+export async function request<T>(
+  config: PerpsBaseConfig,
+  url: string,
+  options: RequestOptions = {},
+  sdkOptions?: SDKRequestOptions
+): Promise<T> {
+  const { retry, ...fetchInit } = options
+  const policy =
+    retry !== undefined
+      ? resolveRetryPolicy(LIFI_RETRY_DEFAULTS, retry, LIFI_REQUEST_KEY)
+      : resolveRetryPolicy(LIFI_RETRY_DEFAULTS, config.retry, LIFI_REQUEST_KEY)
+
+  const headers: Record<string, string> = {
+    'Content-Type': 'application/json',
+    'x-lifi-integrator': config.integrator,
+    'x-lifi-perps-sdk': version,
+    ...(fetchInit.headers as Record<string, string>),
+  }
+
+  if (config.apiKey) {
+    headers['x-lifi-api-key'] = config.apiKey
+  }
+
+  let finalOptions: RequestInit = {
+    ...fetchInit,
+    headers,
+    signal: sdkOptions?.signal ?? fetchInit.signal,
+  }
+
+  if (config.requestInterceptor) {
+    finalOptions = await config.requestInterceptor(url, finalOptions)
+  }
+
+  try {
+    const response = await fetchWithRetry(url, finalOptions, {
+      policy,
+      fetchImpl: config.fetch,
+      signal: sdkOptions?.signal ?? finalOptions.signal ?? undefined,
+    })
+
+    if (!response.ok) {
+      let body: PerpsErrorBody | undefined
+      try {
+        body = await response.json()
+      } catch {}
+
+      const fallbackMessage = `Request failed with status code ${response.status}`
+      if (
+        body &&
+        typeof body.code === 'number' &&
+        typeof body.message === 'string'
+      ) {
+        const error = new PerpsError(body.code, body.message)
+        error.tool = body.tool ?? 'unknown'
+        throw error
+      }
+      const error = new PerpsError(PerpsErrorCode.DefaultError, fallbackMessage)
+      error.tool = 'unknown'
+      throw error
+    }
+
+    return (await response.json()) as T
+  } catch (error) {
+    if (error instanceof PerpsError) {
+      throw error
+    }
+
+    throw new PerpsError(
+      PerpsErrorCode.ServerError,
+      error instanceof Error ? error.message : 'Request failed'
+    )
+  }
+}
+
+/**
+ * Build a URL with a query string from defined params (skips `undefined`).
+ *
+ * @internal
+ */
+export function buildUrl(
+  baseUrl: string,
+  params: Record<string, string | number | boolean | undefined>
+): string {
+  const searchParams = new URLSearchParams()
+
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== undefined) {
+      searchParams.set(key, String(value))
+    }
+  }
+
+  const queryString = searchParams.toString()
+  return queryString ? `${baseUrl}?${queryString}` : baseUrl
+}