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	API key
Production	https://li.quest/v1/perps	Optional
Development	https://develop.li.quest/v1/perps	Required

Production accepts requests with no API key; they use LI.FI’s default fees. Development and Staging require an API key.

Authentication

An API key is optional on Production (https://li.quest/v1/perps). Development and Staging require one. The API key identifies your integration for fees:

• No API key — the request uses LI.FI’s default fees. This is a supported configuration.
• A valid API key — LI.FI validates the key and applies the fees agreed for your integration.
• An invalid API key, or a key that is not linked to an integration — the request is rejected before any fee or order is built.

Register at the LI.FI Partner Portal to get an API key.

Pass the following headers:

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

Header	Required	Description
x-lifi-api-key	No	API key. LI.FI validates it and uses it to identify your integration. Omit it on Production to use LI.FI’s default fees.
x-lifi-integrator	No	Optional assertion of your integrator name. Not authoritative: it never selects the integration on its own.

x-lifi-integrator is an assertion, not a credential

x-lifi-integrator only checks a claim against the identity your API key already established:

• Matches the authenticated identity — accepted.
• Differs from the authenticated identity — ignored. The backend uses the API-key identity and does not reject the request. Send the key’s own integration id, or omit the header.
• Sent with no API key — has no effect. Without a key there is no authenticated identity to match, so the request uses LI.FI’s default fees.

In the SDK, pass these as configuration options:

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

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

The SDK sends x-lifi-integrator only when both apiKey and integrator are set. See Getting Started for the key-only, key-plus-assertion, and no-key configurations.

Hyperliquid builder fee

Hyperliquid orders carry a LI.FI builder fee, which the trading address must approve via the approveBuilderFee setup step. Without the approval, createAction returns 409 / 2070 (SetupRequired).

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 LI.FI API calls through your backend (see Browser apps: proxy pattern). The optional integrator assertion carries no secret and does not change this requirement.

Browser apps: proxy pattern

Point apiUrl at a route on your own server. The route adds x-lifi-api-key (and optionally x-lifi-integrator) and forwards the request to LI.FI. The browser never holds the key.

const UPSTREAM = 'https://li.quest/v1/perps';

export async function handler(request: Request): Promise<Response> {
  const { pathname, search } = new URL(request.url);
  const path = pathname.replace(/^\/api\/perps/, '');
  if (path.split('/')[1] === 'admin') {
    return new Response('Forbidden', { status: 403 });
  }

  const headers = new Headers();
  const contentType = request.headers.get('content-type');
  if (contentType) headers.set('content-type', contentType);
  headers.set('x-lifi-api-key', process.env.LIFI_API_KEY ?? '');
  headers.set('x-lifi-integrator', 'your-app-name');

  const hasBody = request.method !== 'GET' && request.method !== 'HEAD';
  const upstream = await fetch(`${UPSTREAM}${path}${search}`, {
    method: request.method,
    headers,
    body: hasBody ? await request.arrayBuffer() : undefined,
    cache: 'no-store',
  });

  return new Response(upstream.body, {
    status: upstream.status,
    headers: { 'content-type': upstream.headers.get('content-type') ?? 'application/json' },
  });
}

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

const client = createPerpsClient({ apiUrl: '/api/perps' });

Rules for the proxy:

• Forward the request body and content-type untouched.
• Do not cache responses.
• Restrict the path to the routes you use; do not expose admin routes.

The proxy only covers LI.FI HTTP calls. Account reads, checkSetup, and provider WebSocket streams go from the SDK directly to the provider, so they still originate in the browser.

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

Responses include the x-lifi-requestid header for request correlation and debugging. A request that fails before the server creates its request context can have no header.

x-lifi-requestid: 3f2b8c1e-5d4a-4b7e-9a60-1c2d3e4f5a6b

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.

Error Format

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

{
  "code": 2002,
  "tool": "hyperliquid",
  "message": "Invalid request parameters"
}

Field	Type	Description
code	integer	Numeric error code (see Error Codes)
tool	string?	The provider that generated the error. Present when a provider originated the error
message	string	Human-readable error description

HTTP Error Status Codes

Status	Description
400	Validation error — invalid parameters, invalid nonce (2040), or payload mismatch (2050)
401	Authentication error — invalid signature, invalid API key (2013), or terms not accepted (2012)
403	Forbidden — agent not authorized (2011) or missing privilege (2014)
404	Not found — market, order, position, account, route, or other resource does not exist
408	Timeout — an action was submitted but its outcome could not be confirmed in time
409	Conflict — nonce already used, or a recoverable provider setup action is required
410	Gone — nonce expired, retry the operation
422	Unprocessable — venue rejected the operation (2020), insufficient margin or balance, the venue does not support the requested feature (2080), or a transfer between pooled categories (2027)
424	Failed dependency — upstream provider error
429	Too Many Requests — caller spent its request budget for the current window
500	Internal error — DefaultError, ServerError, or SDKError; the message is generic

Rate Limits

Rate limits apply per one-minute window. The backend counts a request against the integration of its API key, so all the keys of one integration share one budget. A key with no integration counts against the key id. A request with no key counts against the hashed client IP.

The default budget is 300 requests each minute. createAction and executeAction have their own default of 30 requests each minute for a request with no key, and for a key with no rateLimit of its own. Contact LI.FI support for higher limits.

Every response carries x-ratelimit-limit, x-ratelimit-remaining, and x-ratelimit-reset. A 429 response also carries retry-after.

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
GET	/meta/referral	Get referral code status for an address
GET	/meta/referral/activity	Get referral activity for an address

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.

Actions

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