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

# Introduction

> LI.FI Perps API overview, authentication, and request format

The LI.FI Perps API provides REST endpoints for perpetual futures trading across multiple providers.

## Base URLs

| Environment | URL                                 |
| ----------- | ----------------------------------- |
| Development | `https://develop.li.quest/v1/perps` |

{/* | Production | `https://li.quest/v1/perps` | */}

## Authentication

All requests require an API key. Register at the [LI.FI Partner Portal](https://portal.li.fi/) to get your API key and integrator name.

Pass the following headers with every request:

```
x-lifi-api-key: your-api-key
x-lifi-integrator: your-app-name
```

| Header              | Required | Description                                                  |
| ------------------- | -------- | ------------------------------------------------------------ |
| `x-lifi-api-key`    | Yes      | API key provided by LI.FI (enforced at infrastructure level) |
| `x-lifi-integrator` | No       | Your integrator identifier for tracking and analytics        |

In the SDK, pass these as configuration options:

```typescript theme={null}
import { createPerpsClient } from '@lifi/perps-sdk';

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

<Warning>
  Never expose your `x-lifi-api-key` in client-side code (browser JavaScript, frontend bundles). The key is visible in browser developer tools and network tabs. For frontend integrations, proxy API calls through your backend to keep the key secret.
</Warning>

## Request Format

* All `POST` request bodies use `application/json`
* Query parameters are used for `GET` requests
* String numeric values (prices, sizes, amounts) avoid floating-point precision issues

## Response Format

Successful responses return JSON with appropriate HTTP status codes:

| Status | Meaning                                                    |
| ------ | ---------------------------------------------------------- |
| `200`  | Success — response body contains requested data            |
| `201`  | Created — resource created and ready for next step         |
| `202`  | Accepted — operation submitted for asynchronous processing |

## Response Headers

All responses include the `x-lifi-requestid` header for request correlation and debugging:

```
x-lifi-requestid: req_abc123xyz789
```

<Info>
  Include the `x-lifi-requestid` value when reporting issues to LI.FI support. This ID is logged server-side and allows us to trace your specific request.
</Info>

## Error Format

All errors follow the same structure with **numeric error codes** (2000+ range):

```json theme={null}
{
  "code": 2002,
  "tool": "hyperliquid",
  "message": "Invalid request parameters"
}
```

| Field     | Type      | Description                                          |
| --------- | --------- | ---------------------------------------------------- |
| `code`    | `integer` | Numeric error code (see [Error Codes](/error-codes)) |
| `tool`    | `string`  | The DEX that generated the error                     |
| `message` | `string`  | Human-readable error description                     |

### HTTP Error Status Codes

| Status | Description                                           |
| ------ | ----------------------------------------------------- |
| `400`  | Validation error — invalid parameters                 |
| `401`  | Authentication error — invalid signature              |
| `403`  | Forbidden — agent not authorized                      |
| `404`  | Not found — market, order, or resource does not exist |
| `408`  | Timeout — request or upstream operation timed out     |
| `409`  | Conflict — nonce already used                         |
| `410`  | Gone — nonce expired, retry the operation             |
| `422`  | Unprocessable — insufficient margin or balance        |
| `424`  | Failed dependency — upstream DEX error                |

## Rate Limits

Rate limits are applied per API key. Contact [LI.FI support](https://portal.li.fi/) for rate limit details and higher tier access.

## Endpoints Overview

### Market Data (Public)

| Method | Path              | Description                                         |
| ------ | ----------------- | --------------------------------------------------- |
| `GET`  | `/providers`      | List providers                                      |
| `GET`  | `/markets`        | List tradeable markets (instruments) for a provider |
| `GET`  | `/assets`         | List the underlying asset registry for a provider   |
| `GET`  | `/marketsContext` | Get live per-market context                         |
| `GET`  | `/ohlcv`          | Get OHLCV chart data                                |
| `GET`  | `/orderbook`      | Get orderbook snapshot                              |
| `GET`  | `/meta`           | Get platform metadata (version and notices)         |
| `GET`  | `/meta/terms`     | Get terms of service and acceptance status          |

### Account

Account-level reads (account summary, positions, orders, fills, activity, single order) are served by the SDK directly from each provider, not by LI.FI HTTP endpoints. Use `@lifi/perps-sdk`: `getAccount`, `getPositions`, `getOrders`, `getFills`, `getActivity`, `getOrder`. See [SDK / Account](/sdk/account/get-account).

### Actions

| Method | Path             | Description                       |
| ------ | ---------------- | --------------------------------- |
| `POST` | `/createAction`  | Build action payloads for signing |
| `POST` | `/executeAction` | Submit signed action payloads     |