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)
storage	StorageAdapter	No	Custom storage adapter for agent keys (see Signing Modes)
disableVersionCheck	boolean	No	Disable SDK version update check (useful in development)
requestInterceptor	RequestInterceptor	No	Modify fetch options before each request
providers	object	No	Provider-specific configuration (see below)

Provider Configuration

The providers option allows provider-specific tuning:

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

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

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, getPrices } 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 prices
const { prices } = await getPrices(client, { provider: 'hyperliquid' });
for (const p of prices) {
  console.log(p.assetId, p.price); // BTC 95000.50
}

For a complete end-to-end example including wallet setup, prerequisites, 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

• Concepts / Signing Modes — USER vs USER_AGENT, agent key storage and management
• Concepts / Action Pattern — The create -> sign -> submit pattern
• Providers / Hyperliquid — Prerequisites, 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