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

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

@@ -0,0 +1,46 @@
+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 {
+  provider: string
+  address: Address
+}
+
+/**
+ * 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.
+ *
+ * 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 account = await getAccount(client, {
+ *   provider: 'hyperliquid',
+ *   address: '0x1234...',
+ * })
+ * console.log(account.balances)
+ * ```
+ * @public
+ */
+export async function getAccount(
+  client: PerpsSDKClient,
+  params: GetAccountParams,
+  options?: SDKRequestOptions
+): Promise<AccountResponse> {
+  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

@@ -0,0 +1,52 @@
+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 {
+  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 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, { 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`, {
+    provider: params.provider,
+    marketIds: params.marketId,
+  })
+  const { markets } = await request<MarketsResponse>(
+    client.config,
+    url,
+    {},
+    options
+  )
+  return markets[0]
+}

package/src/services/getMarkets.ts

@@ -0,0 +1,40 @@
+import type { 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 getMarkets}.
+ *
+ * @public
+ */
+export interface GetMarketsParams {
+  provider: string
+  /** Optional filter — opaque `Market.id`s (not display symbols). */
+  marketIds?: string[]
+}
+
+/**
+ * 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, { provider: 'hyperliquid' })
+ * ```
+ * @public
+ */
+export async function getMarkets(
+  client: PerpsSDKClient,
+  params: GetMarketsParams,
+  options?: SDKRequestOptions
+): Promise<MarketsResponse> {
+  const url = buildUrl(`${client.config.apiUrl}/markets`, {
+    provider: params.provider,
+    marketIds: params.marketIds?.join(','),
+  })
+  return request<MarketsResponse>(client.config, url, {}, options)
+}

package/src/services/getMeta.ts

@@ -0,0 +1,32 @@
+import type { Meta } from '@lifi/perps-types'
+import { request } from '../transport/request.js'
+import type { SDKRequestOptions } from '../types/config.js'
+import type { PerpsSDKClient } from '../types/provider.js'
+
+/**
+ * Get platform metadata: the API version and any active platform-level notices.
+ *
+ * @param client - The SDK client instance
+ * @param options - Request options (e.g., AbortSignal)
+ * @returns Platform version and the list of active notices
+ * @throws {PerpsError} On API error responses
+ * @throws {PerpsError} On network or parsing errors
+ *
+ * @example
+ * ```ts
+ * const client = createPerpsClient({ integrator: 'my-app' })
+ * const { version, notices } = await getMeta(client)
+ * ```
+ * @public
+ */
+export async function getMeta(
+  client: PerpsSDKClient,
+  options?: SDKRequestOptions
+): Promise<Meta> {
+  return request<Meta>(
+    client.config,
+    `${client.config.apiUrl}/meta`,
+    {},
+    options
+  )
+}

package/src/services/getOhlcv.ts

@@ -0,0 +1,52 @@
+import type { OhlcvInterval, OhlcvResponse } 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 getOhlcv}.
+ *
+ * @public
+ */
+export interface GetOhlcvParams {
+  provider: string
+  /** Opaque provider `Market.id` (not `displaySymbol`). */
+  marketId: string
+  interval: OhlcvInterval
+  /** Unix timestamp in milliseconds */
+  startTime?: number
+  /** Unix timestamp in milliseconds */
+  endTime?: number
+  limit?: number
+}
+
+/**
+ * Get OHLCV (candlestick) data for a market.
+ *
+ * @throws {PerpsError} On backend, network, or parsing errors.
+ * @example
+ * ```ts
+ * const { candles } = await getOhlcv(client, {
+ *   provider: 'hyperliquid',
+ *   marketId: 'BTC',
+ *   interval: '1h',
+ *   limit: 100,
+ * })
+ * ```
+ * @public
+ */
+export async function getOhlcv(
+  client: PerpsSDKClient,
+  params: GetOhlcvParams,
+  options?: SDKRequestOptions
+): Promise<OhlcvResponse> {
+  const url = buildUrl(`${client.config.apiUrl}/ohlcv`, {
+    provider: params.provider,
+    marketId: params.marketId,
+    interval: params.interval,
+    startTime: params.startTime,
+    endTime: params.endTime,
+    limit: params.limit,
+  })
+  return request<OhlcvResponse>(client.config, url, {}, options)
+}

package/src/services/getOrder.ts

@@ -0,0 +1,44 @@
+import type { Order } 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 getOrder}.
+ *
+ * @public
+ */
+export interface GetOrderParams {
+  provider: string
+  address: Address
+  id: string
+}
+
+/**
+ * Get a specific order by ID. 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 order = await getOrder(client, {
+ *   provider: 'hyperliquid',
+ *   address: '0x1234...',
+ *   id: '123456',
+ * })
+ * ```
+ * @public
+ */
+export async function getOrder(
+  client: PerpsSDKClient,
+  params: GetOrderParams,
+  options?: SDKRequestOptions
+): Promise<Order> {
+  return requireProvider(client, params.provider).getOrder(
+    { address: params.address, id: params.id },
+    options
+  )
+}

package/src/services/getOrderbook.ts

@@ -0,0 +1,37 @@
+import type { OrderbookResponse } 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 getOrderbook}.
+ *
+ * @public
+ */
+export interface GetOrderbookParams {
+  provider: string
+  /** Opaque provider `Market.id` (not `displaySymbol`). */
+  marketId: string
+  /** Number of levels to return (default varies by DEX) */
+  depth?: number
+}
+
+/**
+ * Get an orderbook backfill snapshot for a market. Pair with a provider WS
+ * subscription for live updates.
+ *
+ * @throws {PerpsError} On backend error responses, network, or parsing errors.
+ * @public
+ */
+export async function getOrderbook(
+  client: PerpsSDKClient,
+  params: GetOrderbookParams,
+  options?: SDKRequestOptions
+): Promise<OrderbookResponse> {
+  const url = buildUrl(`${client.config.apiUrl}/orderbook`, {
+    provider: params.provider,
+    marketId: params.marketId,
+    depth: params.depth,
+  })
+  return request<OrderbookResponse>(client.config, url, {}, options)
+}

package/src/services/getOrders.ts

@@ -0,0 +1,51 @@
+import type { OrdersResponse } 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 getOrders}.
+ *
+ * @public
+ */
+export interface GetOrdersParams {
+  provider: string
+  address: Address
+  /** Optional filter — opaque `Market.id` (not `displaySymbol`) */
+  marketId?: string
+  limit?: number
+  cursor?: string
+}
+
+/**
+ * Get open orders and trigger orders 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 { openOrders, triggerOrders } = await getOrders(client, {
+ *   provider: 'hyperliquid',
+ *   address: '0x1234...',
+ * })
+ * ```
+ * @public
+ */
+export async function getOrders(
+  client: PerpsSDKClient,
+  params: GetOrdersParams,
+  options?: SDKRequestOptions
+): Promise<OrdersResponse> {
+  return requireProvider(client, params.provider).getOrders(
+    {
+      address: params.address,
+      marketId: params.marketId,
+      limit: params.limit,
+      cursor: params.cursor,
+    },
+    options
+  )
+}

package/src/services/getPositions.ts

@@ -0,0 +1,51 @@
+import type { PositionsResponse } 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 getPositions}.
+ *
+ * @public
+ */
+export interface GetPositionsParams {
+  provider: string
+  address: Address
+  /** Optional filter — opaque `Market.id` (not `displaySymbol`) */
+  marketId?: string
+  limit?: number
+  cursor?: string
+}
+
+/**
+ * Get open positions 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 { positions } = await getPositions(client, {
+ *   provider: 'hyperliquid',
+ *   address: '0x1234...',
+ * })
+ * ```
+ * @public
+ */
+export async function getPositions(
+  client: PerpsSDKClient,
+  params: GetPositionsParams,
+  options?: SDKRequestOptions
+): Promise<PositionsResponse> {
+  return requireProvider(client, params.provider).getPositions(
+    {
+      address: params.address,
+      marketId: params.marketId,
+      limit: params.limit,
+      cursor: params.cursor,
+    },
+    options
+  )
+}

package/src/services/getPrices.ts

@@ -0,0 +1,33 @@
+import type { PricesResponse } 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 getPrices}.
+ *
+ * @public
+ */
+export interface GetPricesParams {
+  provider: string
+  /** Optional filter — opaque `Market.id`s (not display symbols). */
+  marketIds?: string[]
+}
+
+/**
+ * Get current prices for markets, optionally filtered by `Market.id`.
+ *
+ * @throws {PerpsError} On backend error responses, network, or parsing errors.
+ * @public
+ */
+export async function getPrices(
+  client: PerpsSDKClient,
+  params: GetPricesParams,
+  options?: SDKRequestOptions
+): Promise<PricesResponse> {
+  const url = buildUrl(`${client.config.apiUrl}/prices`, {
+    provider: params.provider,
+    marketIds: params.marketIds?.join(','),
+  })
+  return request<PricesResponse>(client.config, url, {}, options)
+}

package/src/services/getProviders.ts

@@ -0,0 +1,33 @@
+import type { ProvidersResponse } from '@lifi/perps-types'
+import { request } from '../transport/request.js'
+import type { SDKRequestOptions } from '../types/config.js'
+import type { PerpsSDKClient } from '../types/provider.js'
+
+/**
+ * Get all available providers.
+ *
+ * @param client - The SDK client instance
+ * @param options - Request options (e.g., AbortSignal)
+ * @returns List of supported providers with their authorization requirements
+ * @throws {PerpsError} On API error responses
+ * @throws {PerpsError} On network or parsing errors
+ *
+ * @example
+ * ```ts
+ * const client = createPerpsClient({ integrator: 'my-app' })
+ * const { providers } = await getProviders(client)
+ * console.log(providers) // [{ key: 'hyperliquid', name: 'Hyperliquid', ... }]
+ * ```
+ * @public
+ */
+export async function getProviders(
+  client: PerpsSDKClient,
+  options?: SDKRequestOptions
+): Promise<ProvidersResponse> {
+  return request<ProvidersResponse>(
+    client.config,
+    `${client.config.apiUrl}/providers`,
+    {},
+    options
+  )
+}