Getting Started

Install and configure @lifi/perps-sdk

​

Installation

Install @lifi/perps-sdk plus a provider package for each venue you trade on. Each provider package (@lifi/perps-sdk-provider-hyperliquid, @lifi/perps-sdk-provider-lighter, @lifi/perps-sdk-provider-ondo) declares @lifi/perps-sdk as a peer dependency.

yarn

yarn add @lifi/perps-sdk @lifi/perps-sdk-provider-hyperliquid @lifi/perps-sdk-provider-lighter @lifi/perps-sdk-provider-ondo

​

Configuration

Initialize the Perps SDK client. An API key identifies your integration for fees. The integrator name is an optional assertion of the API key’s identity:

import { createPerpsClient } from '@lifi/perps-sdk';

// Initialize the perps client
const client = createPerpsClient({
  apiKey: 'your-api-key',
});

The SDK supports three client configurations:

import { createPerpsClient } from '@lifi/perps-sdk';

// Key only — fees follow the integration the API key belongs to
const keyOnlyClient = createPerpsClient({ apiKey: 'your-api-key' });

// Key plus assertion — `integrator` is sent as `x-lifi-integrator`. It must
// match the key's identity; a mismatch is warned about and ignored
const keyPlusAssertionClient = createPerpsClient({
  apiKey: 'your-api-key',
  integrator: 'your-app-name',
});

// No key — a supported configuration on Production. Every request uses
// LI.FI's default fees
const noKeyClient = createPerpsClient({});

The SDK sends x-lifi-integrator only when both apiKey and integrator are set. integrator with no apiKey has no effect, because the integration always comes from the API key. See API Reference / Authentication for the full contract.

DEFAULT_API_URL is the Production host (https://li.quest/v1/perps). Pass apiUrl to target another host:

import { createPerpsClient } from '@lifi/perps-sdk';

const client = createPerpsClient({
  integrator: 'your-app-name',
  apiKey: 'your-api-key',
  apiUrl: 'https://develop.li.quest/v1/perps',
});

An API key is optional on Production only. Development (develop.li.quest) and Staging (staging.li.quest) require an API key. On Production, requests with no key use LI.FI’s default fees.

​

Which client?

The SDK has two client surfaces. Build one PerpsClient and use its .client wherever a service function (getProviders, getAssets, getOrders, …) or PerpsWsClient takes a PerpsSDKClient.

Name	Type	Used for
perps	PerpsClient	Setup, trading, withdrawals, onboarding (checkSetup, placeOrder, withdraw, execute)
client	PerpsSDKClient	Service functions and PerpsWsClient; perps.client from a PerpsClient, or the result of createPerpsClient

Snippets in these docs share these names and declare only what is new. Imports, enums, and other variables are always spelled out. Assume these are in scope: perps, client, ws (PerpsWsClient), walletClient (the end-user’s viem wallet client), address and userAddress (Address).

import { PerpsClient, PerpsWsClient } from '@lifi/perps-sdk';
import { hyperliquidProvider } from '@lifi/perps-sdk-provider-hyperliquid';

const perps = new PerpsClient({
  apiKey: 'your-api-key',
  providers: [hyperliquidProvider()],
});
const client = perps.client;
const ws = new PerpsWsClient(client);

​

Configuration Options

These options configure createPerpsClient, the low-level client the service functions (getProviders, getAssets, etc.) take:

Option	Type	Required	Description
integrator	string	No	Optional assertion of your integrator name. Sent only when apiKey is also set. It never changes the integration: a value that differs from the API key’s identity is warned about and ignored. The backend uses the API key’s identity.
apiKey	string	No	API key. Identifies your integration for fees. Omit it on Production to use LI.FI’s default fees. See the note above for Development and Staging.
apiUrl	string	No	Base API URL (defaults to DEFAULT_API_URL, Production)
requestInterceptor	RequestInterceptor	No	Modify fetch options before each request
providers	PerpsProviderPlugin[]	No	Provider plugins that bind each DEX’s read surface to the client (see below)
userWallet	PerpsClientSigner (a viem WalletClient with an account)	No	The end-user’s viem-compatible wallet, used whenever an action descriptor declares signer: USER (browser wallet, private key, or mnemonic account)
retry	RetryConfig	No	HTTP retry behaviour. false disables retries everywhere; a flat RetryPolicy applies one policy across providers; a per-provider object keyed by 'lifi' / 'hyperliquid' / 'lighter' / 'lighter-rh' / 'ondo' (with an optional default) tunes each. Each key is the plugin’s provider key. Built-in defaults apply when omitted.
fetch	typeof fetch	No	Replace the global fetch used by the SDK and provider HTTP clients (instrumentation, proxying, test injection). Does not affect retry policy.

​

PerpsClient constructor options

new PerpsClient(options) — the higher-level class covering setup, trading, and app-level meta actions (see SDK / Actions) — takes a narrower option set. It forwards integrator, apiKey, apiUrl, and providers to an internal createPerpsClient call:

Option	Type	Required	Description
integrator	string	No	Same as createPerpsClient.
apiKey	string	No	Same as createPerpsClient.
apiUrl	string	No	Same as createPerpsClient.
providers	PerpsProviderPlugin[]	No	Same as createPerpsClient.
switchChain	SwitchChainHook	No	Hook invoked before a user-signed EIP-712 action is signed, to switch the user’s wallet to the action’s target chain.

PerpsClient has no userWallet, retry, requestInterceptor, or fetch constructor option, and it cannot take a pre-built low-level client. With a PerpsClient you cannot add request headers, inject fetch, or change the SDK’s retry policy. The only levers are apiUrl (point it at your own proxy, see Browser apps) and the provider plugin factories. Set the end-user wallet after construction with perps.setUserWallet(wallet), and update switchChain at runtime with perps.setSwitchChain(hook).

The SDK bundles its own viem version range. If your app uses a different viem minor, setUserWallet(walletClient) can fail to type-check; cast the wallet client once (walletClient as Parameters<PerpsClient['setUserWallet']>[0]). A viem wallet client is pinned to the chain it was created on. When a wagmi wallet client changes chain, call setUserWallet again, or configure switchChain so the SDK switches the chain before user-signed EIP-712 and EVM steps.

​

Provider Configuration

The providers option takes an array of provider plugins. Each plugin binds a DEX’s read surface to the client, looked up at runtime via client.getProvider(key):

import { createPerpsClient } from '@lifi/perps-sdk';
import { hyperliquidProvider } from '@lifi/perps-sdk-provider-hyperliquid';

const client = createPerpsClient({
  integrator: 'your-app-name',
  apiKey: 'your-api-key',
  providers: [hyperliquidProvider()],
});

Storage for the agent / API-key signer is configured on the provider plugin (e.g. hyperliquidProvider({ storage })), not on createPerpsClient.

​

Request Interceptor

The requestInterceptor option lets you modify request options before each API call. This is useful for adding custom headers, logging, or integrating with authentication systems:

import { createPerpsClient } from '@lifi/perps-sdk';

const client = createPerpsClient({
  integrator: 'your-app-name',
  apiKey: 'your-api-key',
  requestInterceptor: (url: string, options: RequestInit) => {
    console.log(`Request: ${options.method ?? 'GET'} ${url}`);
    return {
      ...options,
      headers: {
        ...options.headers,
        'x-custom-header': 'value',
      },
    };
  },
});

Get an API key from the LI.FI Partner Portal to trade under your own integration. A client with no API key is a supported configuration on Production and uses LI.FI’s default fees.

​

Browser apps: proxy pattern

Never ship an x-lifi-api-key in a browser bundle. Point apiUrl at a same-origin route on your backend instead. The route adds the key and forwards the request. A relative path works:

import { PerpsClient } from '@lifi/perps-sdk';

const perps = new PerpsClient({ apiUrl: '/api/perps' });

The proxy passes through the request body and content type untouched, adds x-lifi-api-key (and optionally x-lifi-integrator), and must not cache; see also API Reference / Browser apps. This handler uses only the Fetch API and works in any runtime that passes it a Request:

const upstream = 'https://li.quest/v1/perps';
const requestHeaders = ['accept', 'content-type'];
const responseHeaders = ['content-type', 'cache-control', 'etag'];

export async function proxy(request: Request, path: string[]): Promise<Response> {
  if (path.some((segment) => /[/\\%;\u0000-\u0020\u007f]/.test(segment))) {
    return new Response('Bad request', { status: 400 });
  }

  const url = new URL(`${upstream}/${path.map(encodeURIComponent).join('/')}`);
  url.search = new URL(request.url).search;

  const headers = new Headers();
  for (const name of requestHeaders) {
    const value = request.headers.get(name);
    if (value) headers.set(name, value);
  }
  headers.set('x-lifi-api-key', process.env.LIFI_API_KEY ?? '');

  const hasBody = request.method !== 'GET' && request.method !== 'HEAD';
  const response = await fetch(url, {
    method: request.method,
    headers,
    body: hasBody ? await request.arrayBuffer() : undefined,
    redirect: 'manual',
    cache: 'no-store',
  });

  const out = new Headers();
  for (const name of responseHeaders) {
    const value = response.headers.get(name);
    if (value) out.set(name, value);
  }
  return new Response(response.body, { status: response.status, headers: out });
}

The proxy covers only the calls to the LI.FI Perps API. Account reads, WebSocket streams, and venue-side signing calls go from the browser straight to the venue:

Call	Path
createAction, executeAction, getProviders, getAssets, getMarkets, getMarketsContext, getOrderbook, getOhlcv, getMeta, getTermsAcceptance	apiUrl (proxied)
getAccount, getPositions, getOrders, getFills, getActivity, WebSocket streams	Venue, direct

​

Rate limits and polling

Rate limits on the LI.FI endpoints apply per integration of the API key. A request with no key counts against the client IP. The account reads and WebSocket streams above hit the venue directly, so the venue’s per-IP budget is the limit that applies to them.

• Prefer WebSocket streams over polling.
• If you poll, use an interval of 10 seconds or more, and do not refetch on every stream frame.
• Retry only on PerpsErrorCode.RateLimitExceeded (2090), with exponential backoff. Do not retry auth errors, ServerError, or MarketNotFound.
• The SDK retries HTTP requests itself. createPerpsClient accepts a retry option; PerpsClient does not, so retries you add in your own layer (for example a query library) stack on top of the SDK’s.

​

Terms acceptance

Every non-meta createAction and executeAction call, which includes checkSetup, setup steps, trading, and withdrawals, fails with 401 / 2012 (TermsNotAccepted) until the address has accepted the current terms version. Check first and onboard when needed:

import { getTermsAcceptance } from '@lifi/perps-sdk';

const terms = await getTermsAcceptance(client, userAddress);
if (!terms.accepted) {
  await perps.submitOnboarding({
    address: userAddress,
    termsVersion: terms.termsVersion,
  });
}

Repeat the check after a terms-version change. See SDK / Actions.

​

Quick Start

Fetch available providers and assets:

import { createPerpsClient, getProviders, getAssets, getMarketsContext } from '@lifi/perps-sdk';

const client = createPerpsClient({
  integrator: 'your-app-name',
  apiKey: 'your-api-key',
});

// List available providers
const { providers } = await getProviders(client);
console.log(providers.map((d) => d.name)); // ['Hyperliquid', ...]

// List assets on a provider
const { assets } = await getAssets(client, { provider: 'hyperliquid' });
console.log(assets.map((a) => a.displaySymbol)); // ['BTC', 'ETH', 'SOL', ...]

// Get current market context
const { prices } = await getMarketsContext(client, { provider: 'hyperliquid' });
for (const p of prices) {
  console.log(p.marketId, p.midPrice); // BTC 95000.50
}

For a complete end-to-end example including wallet setup, account setup, and placing an order, see SDK / Trading — End-to-End Example.

​

Request Cancellation

All service functions accept an optional options parameter (SDKRequestOptions) with an AbortSignal for cancelling in-flight requests:

import { getAssets } from '@lifi/perps-sdk';

const controller = new AbortController();
setTimeout(() => controller.abort(), 5000);

const { assets } = await getAssets(client, {
  provider: 'hyperliquid',
}, { signal: controller.signal });

When the signal fires, the underlying fetch is aborted and the promise rejects with an AbortError.

SDKRequestOptions is { signal? }.

​

Next steps

• Providers / Hyperliquid — Signing Model — Agent provisioning, key storage, and the two-part signing scheme
• Concepts / Action Pattern — The create → authorize → execute pattern
• Providers / Hyperliquid — Setup, signing model, and provider-specific details
• SDK / Trading — All order types, features, and a full end-to-end example
• SDK / Market Data — Prices, orderbooks, and charts