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

# pnpm
pnpm add @lifi/perps-sdk @lifi/perps-sdk-provider-hyperliquid @lifi/perps-sdk-provider-lighter @lifi/perps-sdk-provider-ondo

# npm
npm install @lifi/perps-sdk @lifi/perps-sdk-provider-hyperliquid @lifi/perps-sdk-provider-lighter @lifi/perps-sdk-provider-ondo

# bun
bun 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 selects your fee identity through the Partner Service. The integrator name is an optional assertion that must match the API key’s identity:

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

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

The SDK supports three client configurations:

// Key only — fees follow the API key's Partner Service identity
const keyOnlyClient = createPerpsClient({ apiKey: 'your-api-key' });

// Key plus assertion — the backend checks `integrator` against the key's
// identity and rejects the request if it does not match
const keyPlusAssertionClient = createPerpsClient({
  apiKey: 'your-api-key',
  integrator: 'your-app-name',
});

// No key — a supported configuration. Every request uses the default
// `lifi` fee structure
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 fee identity always comes from the API key. See API Reference / Authentication for the full contract.

DEFAULT_API_URL still resolves to the Development host (https://develop.li.quest/v1/perps). Pass apiUrl explicitly to target the Production host (https://li.quest/v1/perps), where an API key is optional — Development requires one:

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

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; the backend rejects a value that does not match the API key’s authenticated identity.
apiKey	string	No	API key. Selects your fee identity through the Partner Service. Omit it to use the default lifi fee structure. Optional only on the Production host (https://li.quest/v1/perps) — Development (develop.li.quest) and Staging (staging.li.quest) reject any request with no key.
apiUrl	string	No	Base API URL (defaults to DEFAULT_API_URL)
disableVersionCheck	boolean	No	Disable SDK version update check (useful in development)
requestInterceptor	RequestInterceptor	No	Modify fetch options before each request
providers	PerpsProviderPlugin[] | ProviderConfigs	No	Provider plugins (preferred) or per-provider config (see below)
userWallet	WalletClient	No	The end-user’s viem-compatible wallet, used whenever an action descriptor names the user wallet in its signers list (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' / 'ondo' (with an optional default) tunes each. 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[] | ProviderConfigs	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 or retry constructor option. Set the end-user wallet after construction with client.setUserWallet(wallet), and update switchChain at runtime with client.setSwitchChain(hook).

Provider Configuration

The providers option accepts two shapes. Pass an array of provider plugins (preferred for new code) to bind each 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()],
});

Alternatively, pass a keyed ProviderConfigs object for per-provider tuning:

const client = createPerpsClient({
  integrator: 'your-app-name',
  apiKey: 'your-api-key',
  providers: {
    hyperliquid: {
      markets: ['', 'xyz'],  // Filter visible venues (default: all)
    },
  },
});

Provider	Option	Type	Description
hyperliquid.markets	string[]	No	Filter which Hyperliquid venues are visible. '' is the default venue, 'xyz' is the HIP-3 venue. If omitted, all venues are shown.

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:

const client = createPerpsClient({
  integrator: 'your-app-name',
  apiKey: 'your-api-key',
  requestInterceptor: (url, options) => {
    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 receive your own fee identity. A client with no API key is a supported configuration and uses the default lifi fee structure.

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); // 0 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 with an AbortSignal for cancelling in-flight requests:

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.

Next steps

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