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	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: {
      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, 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.marketId, p.price); // 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