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

package/src/services/getMeta.ts

@@ -0,0 +1,30 @@
+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.
+ *
+ * @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

@@ -1,54 +1,48 @@
 import type { OhlcvInterval, OhlcvResponse } 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 getOhlcv}.
+ *
+ * @public
+ */
 export interface GetOhlcvParams {
-  /** DEX to get OHLCV from (e.g., 'hyperliquid') */
-  dex: string
-  /** Market symbol (e.g., 'BTC') */
-  symbol: string
-  /** Candle interval */
+  provider: string
+  /** Opaque provider `Market.id` (not `displaySymbol`). */
+  marketId: string
   interval: OhlcvInterval
-  /** Start time (Unix timestamp in milliseconds) */
+  /** Unix timestamp in milliseconds */
   startTime?: number
-  /** End time (Unix timestamp in milliseconds) */
+  /** Unix timestamp in milliseconds */
   endTime?: number
-  /** Maximum number of candles to return */
   limit?: number
 }
 
 /**
  * Get OHLCV (candlestick) data for a market.
  *
- * @param client - The SDK client instance
- * @param params - Request parameters
- * @param options - Request options (e.g., AbortSignal)
- * @returns OHLCV candle data
- * @throws {HTTPError} On API error responses
- * @throws {PerpsError} On network or parsing errors
- *
+ * @throws {PerpsError} On backend, network, or parsing errors.
  * @example
  * ```ts
- * const client = createPerpsClient({ integrator: 'my-app' })
  * const { candles } = await getOhlcv(client, {
- *   dex: 'hyperliquid',
- *   symbol: 'BTC',
+ *   provider: 'hyperliquid',
+ *   marketId: 'BTC',
  *   interval: '1h',
- *   limit: 100
+ *   limit: 100,
  * })
- * console.log(candles) // [{ t: 1704067200000, o: '94000', h: '95000', ... }]
  * ```
+ * @public
  */
 export async function getOhlcv(
   client: PerpsSDKClient,
   params: GetOhlcvParams,
   options?: SDKRequestOptions
 ): Promise<OhlcvResponse> {
-  const url = buildUrl(`${client.config.apiUrl}/ohlcv/${params.symbol}`, {
-    dex: params.dex,
+  const url = buildUrl(`${client.config.apiUrl}/ohlcv`, {
+    provider: params.provider,
+    marketId: params.marketId,
     interval: params.interval,
     startTime: params.startTime,
     endTime: params.endTime,

package/src/services/getOrder.ts

@@ -1,48 +1,44 @@
-import type { Address, Order } from '@lifi/perps-types'
-import type {
-  PerpsSDKClient,
-  SDKRequestOptions,
-} from '../client/createPerpsClient.js'
-import { buildUrl, request } from '../utils/request.js'
+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 {
-  /** DEX to get order from (e.g., 'hyperliquid') */
-  dex: string
-  /** Wallet address */
+  provider: string
   address: Address
-  /** Order ID */
   id: string
 }
 
 /**
- * Get a specific order by ID.
- *
- * @param client - The SDK client instance
- * @param params - Request parameters
- * @param options - Request options (e.g., AbortSignal)
- * @returns Order details
- * @throws {HTTPError} On API error responses (e.g., 404 if order not found)
- * @throws {PerpsError} On network or parsing errors
+ * 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 client = createPerpsClient({ integrator: 'my-app' })
  * const order = await getOrder(client, {
- *   dex: 'hyperliquid',
+ *   provider: 'hyperliquid',
  *   address: '0x1234...',
- *   id: '123456'
+ *   id: '123456',
  * })
- * console.log(order) // { orderId: '123456', status: 'FILLED', ... }
  * ```
+ * @public
  */
 export async function getOrder(
   client: PerpsSDKClient,
   params: GetOrderParams,
   options?: SDKRequestOptions
 ): Promise<Order> {
-  const url = buildUrl(`${client.config.apiUrl}/order/${params.id}`, {
-    dex: params.dex,
-    address: params.address,
-  })
-  return request<Order>(client.config, url, {}, options)
+  return requireProvider(client, params.provider).getOrder(
+    { address: params.address, id: params.id },
+    options
+  )
 }

package/src/services/getOrderbook.ts

@@ -1,48 +1,36 @@
 import type { OrderbookResponse } 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 getOrderbook}.
+ *
+ * @public
+ */
 export interface GetOrderbookParams {
-  /** DEX to get orderbook from (e.g., 'hyperliquid') */
-  dex: string
-  /** Market symbol (e.g., 'BTC') */
-  symbol: string
+  provider: string
+  /** Opaque provider `Market.id` (not `displaySymbol`). */
+  marketId: string
   /** Number of levels to return (default varies by DEX) */
   depth?: number
 }
 
 /**
- * Get orderbook for a market.
- *
- * @param client - The SDK client instance
- * @param params - Request parameters
- * @param options - Request options (e.g., AbortSignal)
- * @returns Orderbook with bids and asks
- * @throws {HTTPError} On API error responses
- * @throws {PerpsError} On network or parsing errors
+ * Get an orderbook backfill snapshot for a market. Pair with a provider WS
+ * subscription for live updates.
  *
- * @example
- * ```ts
- * const client = createPerpsClient({ integrator: 'my-app' })
- * const { bids, asks } = await getOrderbook(client, {
- *   dex: 'hyperliquid',
- *   symbol: 'BTC',
- *   depth: 20
- * })
- * console.log(bids[0]) // { price: '94999.50', size: '1.5' }
- * console.log(asks[0]) // { price: '95000.50', size: '2.0' }
- * ```
+ * @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/${params.symbol}`, {
-    dex: params.dex,
+  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

@@ -1,39 +1,24 @@
 import type { PricesResponse } 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 getPrices}.
+ *
+ * @public
+ */
 export interface GetPricesParams {
-  /** DEX to get prices from (e.g., 'hyperliquid') */
-  dex: string
-  /** Optional list of symbols to filter (e.g., ['BTC', 'ETH']) */
-  symbols?: string[]
+  provider: string
+  /** Optional filter — opaque `Market.id`s (not display symbols). */
+  marketIds?: string[]
 }
 
 /**
- * Get current prices for markets.
- *
- * @param client - The SDK client instance
- * @param params - Request parameters
- * @param options - Request options (e.g., AbortSignal)
- * @returns Map of symbol to price
- * @throws {HTTPError} On API error responses
- * @throws {PerpsError} On network or parsing errors
- *
- * @example
- * ```ts
- * const client = createPerpsClient({ integrator: 'my-app' })
- * const { prices } = await getPrices(client, { dex: 'hyperliquid' })
- * console.log(prices) // { BTC: '95000.00', ETH: '3400.00', ... }
+ * Get current prices for markets, optionally filtered by `Market.id`.
  *
- * // Filter by symbols
- * const { prices } = await getPrices(client, {
- *   dex: 'hyperliquid',
- *   symbols: ['BTC', 'ETH']
- * })
- * ```
+ * @throws {PerpsError} On backend error responses, network, or parsing errors.
+ * @public
  */
 export async function getPrices(
   client: PerpsSDKClient,
@@ -41,8 +26,8 @@ export async function getPrices(
   options?: SDKRequestOptions
 ): Promise<PricesResponse> {
   const url = buildUrl(`${client.config.apiUrl}/prices`, {
-    dex: params.dex,
-    symbols: params.symbols?.join(','),
+    provider: params.provider,
+    marketIds: params.marketIds?.join(','),
   })
   return request<PricesResponse>(client.config, url, {}, options)
 }

package/src/services/getProviders.ts

@@ -0,0 +1,31 @@
+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.
+ *
+ * @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
+  )
+}

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,32 @@
+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 address - Address whose acceptance status to resolve
+ * @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,122 @@
+import {
+  type FeeTier,
+  type Market,
+  type MarketPrice,
+  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'
+import { getPrices } from './getPrices.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 }, price] = await Promise.all([
+    getOrderbook(client, { provider, marketId: market.id }, options),
+    resolveQuotePrice(client, provider, market.id, options),
+  ])
+
+  return buildQuote({
+    provider,
+    symbol: params.symbol,
+    type: params.type,
+    side: params.side,
+    sizeUsd: params.size,
+    market,
+    price,
+    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 => ('maxLeverage' in market ? type === 'perps' : type === 'spot')
+
+/**
+ * Fetch the live {@link MarketPrice} for `marketId` on `provider`, the source
+ * of the `markPrice` and `funding` a {@link Quote} carries. Shared by the
+ * one-shot {@link resolveQuote} and the streaming quote subscription.
+ *
+ * @throws {PerpsError} `ServerError` when the provider returns no price for the
+ * market.
+ * @internal
+ */
+export async function resolveQuotePrice(
+  client: PerpsSDKClient,
+  provider: string,
+  marketId: string,
+  options?: SDKRequestOptions
+): Promise<MarketPrice> {
+  const { prices } = await getPrices(
+    client,
+    { provider, marketIds: [marketId] },
+    options
+  )
+  const price = prices.find((p) => p.marketId === marketId)
+  if (price === undefined) {
+    throw new PerpsError(
+      PerpsErrorCode.ServerError,
+      `No price returned by '${provider}' for marketId '${marketId}'.`
+    )
+  }
+  return price
+}