> ## Documentation Index
> Fetch the complete documentation index at: https://public-perps-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started

> Install and configure @lifi/perps-sdk

## Installation

```bash theme={null}
# 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:

```typescript theme={null}
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:

```typescript theme={null}
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)`:

```typescript theme={null}
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:

```typescript theme={null}
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. |

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

### 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:

```typescript theme={null}
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',
      },
    };
  },
});
```

<Info>
  Get your integrator name and API key from the [LI.FI Partner Portal](https://portal.li.fi/). Both are required for API access.
</Info>

## Quick Start

Fetch available providers and assets:

```typescript theme={null}
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](/sdk/trading/end-to-end).

## Request Cancellation

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

```typescript theme={null}
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](/providers/hyperliquid/signing-model) — Agent provisioning, key storage, and the two-part signing scheme
* [Concepts / Action Pattern](/concepts/action-pattern) — The create -> sign -> submit pattern
* [Providers / Hyperliquid](/providers/hyperliquid) — Setup, signing model, and provider-specific details
* [SDK / Trading](/sdk/trading/placing-orders) — All order types, features, and a full end-to-end example
* [SDK / Assets](/sdk/assets) — Prices, orderbooks, and charts