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

Authentication

An API key is optional. It is the only way to receive a fee identity other than the platform default:

• No API key — every request uses the default lifi fee structure. This is a supported configuration, not a fallback.
• A valid API key — LI.FI validates the key against the Partner Service and uses its integrationId as your fee identity for the request.
• An invalid API key, or a valid key with no integration mapping — the request is rejected before any fee or order is built.
• A temporary Partner Service communication failure while a key is supplied — the request falls back to the default lifi fee structure. It never uses x-lifi-integrator as a substitute identity.

This design closes a gap where a client could select another integration’s fee tier by sending an arbitrary x-lifi-integrator value with no proof of ownership: the API key, not the header, decides fee identity.

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. Validated against the Partner Service; its integrationId selects your fee identity. Omit it to use the default lifi fee structure.
x-lifi-integrator	No	Optional assertion of your integrator name. Not authoritative: it never selects a fee identity 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 — rejected with a stable error.
• Sent with no API key — has no effect. Without a key there is no authenticated identity to match, so the request uses the default lifi fee structure.

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 requires an explicit builder fee approval before LI.FI can route orders through the account. If your authenticated identity has no matching approval, order requests fail with a setup-required error and never fall back to a fee-free order. Complete the approveBuilderFee setup step first.

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. The optional integrator assertion carries no secret and does not change this requirement.

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

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 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, or a recoverable provider setup action is required
410	Gone — nonce expired, retry the operation
422	Unprocessable — insufficient margin or balance, or the venue does not support the requested feature
424	Failed dependency — upstream DEX error
429	Too Many Requests — caller spent its request budget for the current window

Rate Limits

Rate limits are counted per one-minute window against the caller’s identity, in this order: the Partner-Service integration id an API key maps to, then the raw API-key id when the key has no integration mapping, then the hashed client IP for requests with no API key. Contact LI.FI support 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.

Actions

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