Integrating without the SDK

Call the perps API directly: read provider descriptors, create actions, sign each step, and send it according to its relay

@lifi/perps-sdk is the supported integration path. The SDK satisfies setup steps, exposes the recommended option of each choice without applying it, runs the steps in sequence, and makes the client-side venue calls. This page is for callers that cannot use the SDK. You then take over each of those duties.

What the SDK does for you

Duty	SDK behavior	Your duty when you call the API directly
Satisfaction	checkSetup() reads the account and reports which setup steps are still open	Decide for each step whether it is satisfied. See Decide whether a step is satisfied.
Defaults	The SDK never applies a choice on its own. It exposes default as a recommendation.	Pick an option. Nothing changes until you execute it.
Sequencing	The SDK runs steps in sequence order and refuses a step while a lower step is open	Run the steps in ascending sequence.
Client-side venue calls	The SDK sends every relay: CLIENT step to the venue itself	Send each CLIENT step yourself. See relay: CLIENT.
Signing	The provider plugin holds the agent key, the Lighter key, the Ondo API key, and the session	Produce each signature yourself.

The flow

1. Read the descriptors. Call GET /v1/perps/providers. Each entry in setup and actions declares signer, signingMethod, and relay. See Provider Fields.

2. Create the step. Call POST /v1/perps/createAction with the descriptor type as action. The response lists the staged steps.

3. Sign each step according to the descriptor signingMethod:

   signingMethod	Staged step field	What you produce
   eip712	typedData	signature: the EIP-712 signature of typedData
   wasmBlob	wasmSignParams	signedTx: { txType, txInfo, txHash } from the provider’s WASM signer. See Lighter Signing Model.
   evmTx	txParams	txHash: the hash of the transaction your wallet broadcast for that leg
   hmac	request	hmac: { keyId, timestampMs, signature }. See Ondo Signing Model.
   siwe	siwe	signature: the personal_sign signature of siwe.message
   session	session or request	Nothing to sign. The client makes the venue call with its session.

4. Send the signed step according to the descriptor relay:

   • API: post the signed steps to POST /v1/perps/executeAction.
   • CLIENT: send the step to the venue yourself. Nothing reaches LI.FI. See relay: CLIENT.

A step that has signer: USER needs the user’s wallet or consent. A step that has signer: SDK needs no user interaction, but you must still produce its signature or call yourself.

relay: API

Post the signed steps to the same perps API base that served createAction. Send the steps in the same shape and order that createAction returned. Copy each staged field, such as typedData, from the createAction step without a change. In the example, the value "<from createAction>" stands for that original field.

POST https://li.quest/v1/perps/executeAction
x-lifi-api-key: your-api-key

{
  "provider": "hyperliquid",
  "address": "0x1234567890abcdef1234567890abcdef12345678",
  "action": "approveBuilderFee",
  "actions": [
    {
      "action": "approveBuilderFee",
      "typedData": "<from createAction>",
      "signature": "0xabcd1234..."
    }
  ]
}

{
  "results": [
    { "action": "approveBuilderFee", "success": true }
  ]
}

Lighter deposit acknowledgement

deposit is an evmTx action with relay: API. The user’s wallet broadcasts each leg. executeAction does not broadcast anything. It receives the signed steps as the acknowledgement of the deposit.

createAction returns one step per leg: an ERC-20 approve, then the bridge deposit.

{
  "provider": "lighter",
  "address": "0x1234567890abcdef1234567890abcdef12345678",
  "action": "deposit",
  "params": {
    "amount": "100",
    "tokenAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "chainId": 1
  }
}

Broadcast the legs in order. Then send each step with the txHash of its transaction. Do not change txParams. LI.FI matches the steps against the staged action.

{
  "provider": "lighter",
  "address": "0x1234567890abcdef1234567890abcdef12345678",
  "action": "deposit",
  "actions": [
    {
      "action": "deposit",
      "txParams": {
        "chainId": 1,
        "to": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
        "functionName": "approve",
        "args": ["0xBridgeContract", "100"],
        "abi": ["function approve(address spender, uint256 amount) external returns (bool)"]
      },
      "txHash": "0xaaaa..."
    },
    {
      "action": "deposit",
      "txParams": {
        "chainId": 1,
        "to": "0xBridgeContract",
        "functionName": "deposit",
        "args": ["0x1234567890abcdef1234567890abcdef12345678", 3, 0, "100"],
        "abi": ["function deposit(address _to, uint16 _assetIndex, uint8 _routeType, uint256 _amount) external payable"]
      },
      "txHash": "0xbbbb..."
    }
  ]
}

The response has one result per step. The orderId field carries the txHash:

{
  "results": [
    { "action": "deposit", "success": true, "orderId": "0xaaaa..." },
    { "action": "deposit", "success": true, "orderId": "0xbbbb..." }
  ]
}

The example values for args, to, and the asset index are placeholders. Use the values from your createAction response.

relay: CLIENT

The client sends these steps to the venue itself. LI.FI does not receive them, and you never call executeAction for them.

Each row gives the venue endpoint, the method, the authentication, and the staged-step fields that make up the body.

Lighter

Send Lighter steps to the REST base of the provider instance:

Provider key	REST base
lighter	https://mainnet.zklighter.elliot.ai
lighter-rh	https://api.rh.lighter.xyz

Both steps are form posts. Send Content-Type: application/x-www-form-urlencoded. Put a Lighter auth token in the Authorization header, without a prefix. Make the token with the Lighter signer’s CreateAuthToken function. Use the API key that registerApiKey registered and a short deadline. The SDK uses five minutes.

The staged step is a WasmBlobActionStep, but it has no signed blob. Read the body fields from its wasmSignParams.

Step (action)	Method and endpoint	Authentication	Body fields (from wasmSignParams)
accountType	POST /api/v1/changeAccountTier	Lighter auth token	account_index, new_tier (plus or premium)
setReferrer	POST /api/v1/referral/use	Lighter auth token	l1_address, referral_code, x

The response body carries a code. 200 means success. Any other code is a venue rejection. For setReferrer, code 41003 means the account already has a referral code. Treat it as settled.

Ondo

Send Ondo steps to https://api.ondoperps.xyz. The sandbox base is https://api.ondoperps-sandbox.xyz. Every response is an envelope, { success, result }. Read the value from result.

Except siweLogin, each step authenticates with the session token from siweLogin, sent as Authorization: Bearer <token>. All bodies are JSON.

Step (action)	Method and endpoint	Authentication	Body fields
siweLogin	POST /v1/auth/erc-4361/login/complete_challenge	None	id: siwe.challengeId from the staged step. signature: the wallet’s personal_sign signature of siwe.message. The result carries token, the session JWT.
createDepositAddress	GET /v1/account, then POST /v1/provision_address	Session JWT	The staged session marker fixes network: "ethereum", symbol: "USDC", and depositDestination: { wallet: "margin" }. The GET returns accountID. Send network, symbol, and deposit_destination: { id: accountID, wallet: "margin" }.
acceptProviderTerms	POST /v1/agreement	Session JWT	termsVersion and privacyVersion. The staged session is empty. Send the current versions, which are both 1.
registerApiKey	POST /v1/api_keys	Session JWT	name: "lifi-perps" and scopes: ["trade", "transfer"]. The staged session is empty. The result carries keyId and secretKey. Store both. The secret is shown once, and it signs the hmac trading steps.
setReferrer	The request.method and request.path of the staged step	Session JWT	The staged step is a request. Send request.body, which holds the referral code, as JSON.

An Ondo account holds at most 10 API keys. See Ondo Setup for how the SDK reclaims a slot.

Decide whether a step is satisfied

Run the steps in ascending sequence. A step can depend on every lower step being satisfied. For example, Lighter setReferrer uses the API key that registerApiKey registers.

Steps with relay: API and no options. Call createAction for the step type. Use the descriptor params, which are empty for most steps. An empty actions array means the step is satisfied. A non-empty array means you must sign and submit the staged steps. For Lighter registerApiKey, pass knownPublicKey (the public key you hold locally) so the backend can tell that the key at its slot is yours.

Steps with relay: CLIENT. LI.FI cannot see the venue state for these steps. Read it from the venue:

Provider	Step	Satisfied when
Lighter	setReferrer	GET /api/v1/referral/userReferrals?l1_address=<address> (Lighter auth token) returns a non-empty used_code
Ondo	siweLogin	You hold a session token that has not expired (expirationSecs)
Ondo	createDepositAddress	POST /v1/wallet/deposit_address/list with { "coins": ["USDC"], "network": "ethereum" } (session JWT) returns an Ethereum USDC address
Ondo	acceptProviderTerms	GET /v1/account returns termsVersion and privacyVersion equal to the current versions
Ondo	registerApiKey	You hold an API key that has the trade and transfer scopes
Ondo	setReferrer	GET /v1/account/referral returns a result that is not null

Choice steps. A step with options is satisfied when the account’s current value matches one option. Read the current value from the venue:

Provider	Step	Current value source	Option params compared
Hyperliquid	accountMode	POST https://api.hyperliquid.xyz/info with { "type": "userAbstraction", "user": "<address>" }. A value of null, default, or disabled reads as disabled (Manual).	mode
Lighter	accountMode	account_trading_mode from GET /api/v1/account?by=l1_address&value=<address>: 0 is simpleTradingAccount, 1 is unifiedTradingAccount	mode
Lighter	accountType	user_tier_name from GET /api/v1/accountLimits?account_index=<index> (Lighter auth token)	tier

A step is satisfied when the value you read matches an option, for example plus or premium for the Lighter accountType step. If no option matches, the step is not satisfied.

For a choice step, the option with default: true is the recommended option. It is only a suggestion. Nothing is changed until you execute an option. To execute an option, call createAction with the option type and params. Then sign the staged step, and send it according to the descriptor relay.

{
  "provider": "lighter",
  "address": "0x1234567890abcdef1234567890abcdef12345678",
  "action": "accountType",
  "params": { "tier": "plus" }
}

The response is one WasmBlobActionStep. Read account_index and new_tier from its wasmSignParams, and post them to /api/v1/changeAccountTier as described above.

Revoke a setup step

A satisfied step can carry a revoke value. It names an entry in actions. To undo the step, call createAction with that type and empty params, except revokeSessionAgent, which takes agentAddress. Sign the staged steps and send them according to the relay of that entry. An empty actions array means there is nothing to revoke. The step becomes unsatisfied, so it stages again.

Step	revoke	Provider
approveAgent	revokeSessionAgent (agentAddress of the session agent)	Hyperliquid
approveBuilderFee	revokeBuilderFee	Hyperliquid
approveIntegrator	revokeIntegrator	Lighter

Errors

Lighter accepts integrator approvals and integrator-routed orders only from Plus or Premium accounts. Otherwise executeAction returns SetupRequired (2070). A relay: CLIENT call that you send to Lighter yourself gets the raw venue code 21520. Set the tier with the accountType step, then retry.

See Error Codes for the codes that createAction and executeAction return.