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

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
+  )
+}

package/src/services/executeAction.ts

@@ -0,0 +1,56 @@
+import type {
+  ActionType,
+  ExecuteActionResponse,
+  SignedActionStep,
+} 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 executeAction}.
+ *
+ * @public
+ */
+export interface ExecuteActionParams {
+  provider: string
+  address: Address
+  signerAddress?: Address
+  action: ActionType
+  actions: SignedActionStep[]
+}
+
+/**
+ * Submit client-signed `ActionStep`s to the backend for execution. This is a
+ * money-moving write — the request is never auto-retried (the signed bytes
+ * could already have landed on a transport failure).
+ *
+ * @throws {PerpsError} On backend error responses, network, or parsing errors.
+ * @public
+ */
+export async function executeAction(
+  client: PerpsSDKClient,
+  params: ExecuteActionParams,
+  options?: SDKRequestOptions
+): Promise<ExecuteActionResponse> {
+  return request<ExecuteActionResponse>(
+    client.config,
+    `${client.config.apiUrl}/executeAction`,
+    {
+      method: 'POST',
+      // Money-moving write: a network/5xx failure is outcome-unknown, so the
+      // request must never be auto-resubmitted (the signed bytes could already
+      // have landed). Retries stay enabled for reads and `createAction`.
+      retry: false,
+      body: JSON.stringify({
+        provider: params.provider,
+        address: params.address,
+        signerAddress: params.signerAddress,
+        action: params.action,
+        actions: params.actions,
+      }),
+    },
+    options
+  )
+}

package/src/services/getAccount.ts

@@ -1,47 +1,46 @@
-import type { AccountResponse, Address } from '@lifi/perps-types'
-import type {
-  PerpsSDKClient,
-  SDKRequestOptions,
-} from '../client/createPerpsClient.js'
-import { buildUrl, request } from '../utils/request.js'
+import type { AccountResponse } from '@lifi/perps-types'
+import type { Address } from 'viem'
+import { requireProvider } from '../client/requireProvider.js'
+import type { SDKRequestOptions } from '../types/config.js'
+import type { PerpsSDKClient } from '../types/provider.js'
 
+/**
+ * Parameters for {@link getAccount}.
+ *
+ * @public
+ */
 export interface GetAccountParams {
-  /** DEX to get account from (e.g., 'hyperliquid') */
-  dex: string
-  /** Wallet address */
+  provider: string
   address: Address
 }
 
 /**
- * Get account information including balances, positions, and open orders.
+ * Get account information (balances, margin, fee tier, typed config).
+ * Delegates to the registered venue plugin (direct-to-venue); requires the
+ * provider plugin to be registered on the client.
  *
- * @param client - The SDK client instance
- * @param params - Request parameters
- * @param options - Request options (e.g., AbortSignal)
- * @returns Account details
- * @throws {HTTPError} On API error responses
- * @throws {PerpsError} On network or parsing errors
+ * Use {@link getPositions} and {@link getOrders} to fetch positions and orders
+ * separately.
  *
+ * @throws {PerpsError} When the provider plugin is not registered, or on
+ *   backend / network / parsing errors.
  * @example
  * ```ts
- * const client = createPerpsClient({ integrator: 'my-app' })
  * const account = await getAccount(client, {
- *   dex: 'hyperliquid',
- *   address: '0x1234...'
+ *   provider: 'hyperliquid',
+ *   address: '0x1234...',
  * })
- * console.log(account.balances) // [{ currency: 'USDC', amount: '10000.00' }]
- * console.log(account.positions) // [{ symbol: 'BTC', side: 'LONG', ... }]
- * console.log(account.openOrders) // [{ id: '123', symbol: 'BTC', ... }]
+ * console.log(account.balances)
  * ```
+ * @public
  */
 export async function getAccount(
   client: PerpsSDKClient,
   params: GetAccountParams,
   options?: SDKRequestOptions
 ): Promise<AccountResponse> {
-  const url = buildUrl(`${client.config.apiUrl}/account`, {
-    dex: params.dex,
-    address: params.address,
-  })
-  return request<AccountResponse>(client.config, url, {}, options)
+  return requireProvider(client, params.provider).getAccount(
+    { address: params.address },
+    options
+  )
 }

package/src/services/getActivity.ts

@@ -0,0 +1,57 @@
+import type { ActivitiesResponse, ActivityType } from '@lifi/perps-types'
+import type { Address } from 'viem'
+import { requireProvider } from '../client/requireProvider.js'
+import type { SDKRequestOptions } from '../types/config.js'
+import type { PerpsSDKClient } from '../types/provider.js'
+
+/**
+ * Parameters for {@link getActivity}.
+ *
+ * @public
+ */
+export interface GetActivityParams {
+  provider: string
+  address: Address
+  limit?: number
+  cursor?: string
+  /** Filter: activity after this timestamp (ms) */
+  startTime?: number
+  /** Filter: activity before this timestamp (ms) */
+  endTime?: number
+  type?: ActivityType[]
+}
+
+/**
+ * Get account activity (deposits, withdrawals, liquidations, funding payments).
+ * Delegates to the registered venue plugin (direct-to-venue); requires the
+ * provider plugin to be registered on the client.
+ *
+ * @throws {PerpsError} When the provider plugin is not registered, or on
+ *   backend / network / parsing errors.
+ * @example
+ * ```ts
+ * const { items, pagination } = await getActivity(client, {
+ *   provider: 'hyperliquid',
+ *   address: '0x1234...',
+ *   limit: 50,
+ * })
+ * ```
+ * @public
+ */
+export async function getActivity(
+  client: PerpsSDKClient,
+  params: GetActivityParams,
+  options?: SDKRequestOptions
+): Promise<ActivitiesResponse> {
+  return requireProvider(client, params.provider).getActivity(
+    {
+      address: params.address,
+      limit: params.limit,
+      cursor: params.cursor,
+      startTime: params.startTime,
+      endTime: params.endTime,
+      type: params.type,
+    },
+    options
+  )
+}

package/src/services/getAssets.ts

@@ -0,0 +1,38 @@
+import type { AssetsResponse } from '@lifi/perps-types'
+import { buildUrl, request } from '../transport/request.js'
+import type { SDKRequestOptions } from '../types/config.js'
+import type { PerpsSDKClient } from '../types/provider.js'
+
+/**
+ * Parameters for {@link getAssets}.
+ *
+ * @public
+ */
+export interface GetAssetsParams {
+  provider: string
+}
+
+/**
+ * Get the token/asset registry for a provider. Thin pass-through to the
+ * LI.FI backend's Valkey-cached `/perps/assets` route, which centralises the
+ * `asset id → symbol → logoURI` join so the SDK never calls a provider's
+ * REST API directly for static registry data.
+ *
+ * @throws {PerpsError} On backend, network, or parsing errors.
+ * @example
+ * ```ts
+ * const client = createPerpsClient({ integrator: 'my-app' })
+ * const { assets } = await getAssets(client, { provider: 'lighter' })
+ * ```
+ * @public
+ */
+export async function getAssets(
+  client: PerpsSDKClient,
+  params: GetAssetsParams,
+  options?: SDKRequestOptions
+): Promise<AssetsResponse> {
+  const url = buildUrl(`${client.config.apiUrl}/assets`, {
+    provider: params.provider,
+  })
+  return request<AssetsResponse>(client.config, url, {}, options)
+}

package/src/services/getFills.ts

@@ -0,0 +1,55 @@
+import type { FillsResponse } from '@lifi/perps-types'
+import type { Address } from 'viem'
+import { requireProvider } from '../client/requireProvider.js'
+import type { SDKRequestOptions } from '../types/config.js'
+import type { PerpsSDKClient } from '../types/provider.js'
+
+/**
+ * Parameters for {@link getFills}.
+ *
+ * @public
+ */
+export interface GetFillsParams {
+  provider: string
+  address: Address
+  limit?: number
+  cursor?: string
+  /** Filter: fills after this timestamp (ms) */
+  startTime?: number
+  /** Filter: fills before this timestamp (ms) */
+  endTime?: number
+}
+
+/**
+ * Get order fills for an account. Delegates to the registered venue plugin
+ * (direct-to-venue); requires the provider plugin to be registered on the
+ * client.
+ *
+ * @throws {PerpsError} When the provider plugin is not registered, or on
+ *   backend / network / parsing errors.
+ * @example
+ * ```ts
+ * const { items, pagination } = await getFills(client, {
+ *   provider: 'hyperliquid',
+ *   address: '0x1234...',
+ *   limit: 50,
+ * })
+ * ```
+ * @public
+ */
+export async function getFills(
+  client: PerpsSDKClient,
+  params: GetFillsParams,
+  options?: SDKRequestOptions
+): Promise<FillsResponse> {
+  return requireProvider(client, params.provider).getFills(
+    {
+      address: params.address,
+      limit: params.limit,
+      cursor: params.cursor,
+      startTime: params.startTime,
+      endTime: params.endTime,
+    },
+    options
+  )
+}

package/src/services/getMarket.ts

@@ -1,41 +1,52 @@
-import type { Market } from '@lifi/perps-types'
-import type {
-  PerpsSDKClient,
-  SDKRequestOptions,
-} from '../client/createPerpsClient.js'
-import { buildUrl, request } from '../utils/request.js'
+import type { Market, MarketsResponse } from '@lifi/perps-types'
+import { buildUrl, request } from '../transport/request.js'
+import type { SDKRequestOptions } from '../types/config.js'
+import type { PerpsSDKClient } from '../types/provider.js'
 
+/**
+ * Parameters for {@link getMarket}.
+ *
+ * @public
+ */
 export interface GetMarketParams {
-  /** DEX to get market from (e.g., 'hyperliquid') */
-  dex: string
-  /** Market symbol (e.g., 'BTC') */
-  symbol: string
+  provider: string
+  /**
+   * Opaque provider `Market.id` (e.g. `"BTC"`, `"xyz:PURR"`, `"@142"` on
+   * Hyperliquid; `"0"`, `"1"` on Lighter). Pass a `displaySymbol` here and
+   * lookups will 404 for providers where the two diverge.
+   */
+  marketId: string
 }
 
 /**
- * Get a specific market by symbol.
- *
- * @param client - The SDK client instance
- * @param params - Request parameters
- * @param options - Request options (e.g., AbortSignal)
- * @returns Market details
- * @throws {HTTPError} On API error responses (e.g., 404 if market not found)
- * @throws {PerpsError} On network or parsing errors
+ * Get a specific market by its opaque marketId. Requests the single market
+ * from the backend `/markets` route (filtered by `marketIds`) and returns the
+ * first match; the backend responds 404 (thrown as a {@link PerpsError}) when
+ * nothing matches.
  *
+ * @throws {PerpsError} On backend (e.g. 404), network, or parsing errors.
  * @example
  * ```ts
  * const client = createPerpsClient({ integrator: 'my-app' })
- * const market = await getMarket(client, { dex: 'hyperliquid', symbol: 'BTC' })
- * console.log(market) // { symbol: 'BTC', markPrice: '95000.00', ... }
+ * const market = await getMarket(client, { provider: 'hyperliquid', marketId: 'BTC' })
+ * console.log(market.baseAsset.displaySymbol)
  * ```
+ * @public
  */
 export async function getMarket(
   client: PerpsSDKClient,
   params: GetMarketParams,
   options?: SDKRequestOptions
 ): Promise<Market> {
-  const url = buildUrl(`${client.config.apiUrl}/markets/${params.symbol}`, {
-    dex: params.dex,
+  const url = buildUrl(`${client.config.apiUrl}/markets`, {
+    provider: params.provider,
+    marketIds: params.marketId,
   })
-  return request<Market>(client.config, url, {}, options)
+  const { markets } = await request<MarketsResponse>(
+    client.config,
+    url,
+    {},
+    options
+  )
+  return markets[0]
 }

package/src/services/getMarkets.ts

@@ -1,37 +1,40 @@
 import type { MarketsResponse } from '@lifi/perps-types'
-import type {
-  PerpsSDKClient,
-  SDKRequestOptions,
-} from '../client/createPerpsClient.js'
-import { buildUrl, request } from '../utils/request.js'
+import { buildUrl, request } from '../transport/request.js'
+import type { SDKRequestOptions } from '../types/config.js'
+import type { PerpsSDKClient } from '../types/provider.js'
 
+/**
+ * Parameters for {@link getMarkets}.
+ *
+ * @public
+ */
 export interface GetMarketsParams {
-  /** DEX to get markets from (e.g., 'hyperliquid') */
-  dex: string
+  provider: string
+  /** Optional filter — opaque `Market.id`s (not display symbols). */
+  marketIds?: string[]
 }
 
 /**
- * Get all available markets for a DEX.
- *
- * @param client - The SDK client instance
- * @param params - Request parameters
- * @param options - Request options (e.g., AbortSignal)
- * @returns List of available markets
- * @throws {HTTPError} On API error responses
- * @throws {PerpsError} On network or parsing errors
+ * Get all available markets for a provider. Thin pass-through to the LI.FI
+ * backend's Valkey-cached `/perps/markets` route — the canonical source of
+ * public market data for widget consumers.
  *
+ * @throws {PerpsError} On backend, network, or parsing errors.
  * @example
  * ```ts
  * const client = createPerpsClient({ integrator: 'my-app' })
- * const { markets } = await getMarkets(client, { dex: 'hyperliquid' })
- * console.log(markets) // [{ symbol: 'BTC', name: 'Bitcoin', ... }]
+ * const { markets } = await getMarkets(client, { provider: 'hyperliquid' })
  * ```
+ * @public
  */
 export async function getMarkets(
   client: PerpsSDKClient,
   params: GetMarketsParams,
   options?: SDKRequestOptions
 ): Promise<MarketsResponse> {
-  const url = buildUrl(`${client.config.apiUrl}/markets`, { dex: params.dex })
+  const url = buildUrl(`${client.config.apiUrl}/markets`, {
+    provider: params.provider,
+    marketIds: params.marketIds?.join(','),
+  })
   return request<MarketsResponse>(client.config, url, {}, options)
 }