Getting Started

Install and configure @lifi/perps-sdk

Installation

# yarn
yarn add @lifi/perps-sdk

# pnpm
pnpm add @lifi/perps-sdk

# npm
npm install @lifi/perps-sdk

# bun
bun add @lifi/perps-sdk

Configuration

Initialize the Perps SDK client:

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

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

The SDK targets DEFAULT_API_URL (https://develop.li.quest/v1/perps) by default. Override with apiUrl if needed:

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

Configuration Options

Option	Type	Required	Description
integrator	string	Yes	Integrator identifier
apiKey	string	Yes	API key for authenticated requests
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' (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.

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 your integrator name and API key from the LI.FI Partner Portal. Both are required for API access.

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