PerpsClient Methods - @lifi/perps-sdk

Complete reference for PerpsClient trading and setup methods. Authorization follows each provider’s ProviderAction.signer and signingMethod: order-management methods normally use the plugin’s SDK-managed credential, while user-authorized operations such as Hyperliquid sendAsset can invoke the wallet.

Write methods return { results } and do not throw on a venue rejection: check results[i].status (and errorCode / error when it is Failed or Indeterminate). Thrown PerpsErrors cover transport, validation and signing failures with no report. A thrown PerpsExecutionError carries the known results in response.results. See Execution reports and Error Handling.

Every provider action (setup, trading, withdrawals) fails with 401 / 2012 (TermsNotAccepted) until the address has accepted the current terms version. See Error Handling.

setUserWallet

Set or update the end-user wallet. Call this when the user connects their wallet (for example, from wagmi’s useWalletClient()); pass undefined to clear it when the wallet disconnects.

import type { WalletClient } from 'viem';

perps.setUserWallet(walletClient);

// Later, on wallet disconnect:
perps.setUserWallet(undefined);

Field	Type	Required	Description
`userWallet`	`WalletClient \| undefined`	Yes	viem-compatible wallet client; pass `undefined` to clear

The SDK bundles its own viem range. If your app uses a different viem version, cast the wallet once (walletClient as Parameters<PerpsClient['setUserWallet']>[0]). A viem wallet client stays on the chain it was created on: call setUserWallet again when the wallet’s chain changes, or configure setSwitchChain so the SDK switches before EIP-712 and EVM legs. The wallet is used for provider-declared USER authorization, including setup signatures, SIWE, EVM deposit transactions, Lighter’s REGISTER_API_KEY countersignature, and user-signed transfers or withdrawals. Order-management actions use each plugin’s SDK-managed credential and do not reach this wallet.

setSwitchChain

Set or replace the chain-switching hook. The hook is invoked before a USER-signed EIP-712 action (including meta actions) whose domain chainId differs from the wallet’s. It receives the target chainId and must return a wallet client on that chain. Returning undefined, or a wallet on the wrong chain, throws a PerpsError (SDKError). The hook can also be provided once at construction via the switchChain option on PerpsClientOptions.

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

const switchChain: SwitchChainHook = async (chainId) => {
  await walletClient.switchChain({ id: chainId });
  return walletClient;
};

perps.setSwitchChain(switchChain);

// Later, to remove it:
perps.setSwitchChain(undefined);

Field	Type	Required	Description
`switchChain`	`SwitchChainHook \| undefined`	Yes	`(chainId: number) => Promise<PerpsClientSigner \| undefined>`; pass `undefined` to clear

getMarketSettings

Read the current venue-side margin mode and leverage that the next order on a market will use.

const settings = await perps.getMarketSettings({
  provider: 'hyperliquid',
  address: userAddress,
  market: { marketId: 'BTC', categoryId: 'hyperliquid' },
});

console.log(settings.marginMode, settings.leverage);

Field	Type	Required	Description
`provider`	`string`	Yes	Provider identifier
`address`	`string`	Yes	User wallet address
`market`	`MarketRef`	Yes	Canonical market reference

Returns: MarketSettings — { marginMode, leverage }. The read resolves the venue value or throws. Throws: PerpsError with ValidationError for a spot market. On Hyperliquid, it throws AccountNotFound when the wallet has no venue account. On Ondo, it throws SetupRequired when no session is stored and Unauthorized when Ondo rejects the session. On Lighter, it needs no token and returns the venue default for a wallet with no Lighter account. See Account access. After a write (placeOrder with leverage, updatePositionMargin, sendAsset), the venue’s settings, account, orders and fills reads can return pre-write data for a couple of seconds. Update your UI optimistically and re-read once after a short delay.

placeOrder

Place an order. Builds the action, auto-signs through the provider plugin, and submits in one call.

import { OrderSide, OrderType } from '@lifi/perps-sdk';

const result = await perps.placeOrder({
  address: userAddress,
  provider: 'hyperliquid',
  market: { marketId: 'BTC', categoryId: 'hyperliquid' },
  side: OrderSide.BUY,
  type: OrderType.LIMIT,
  size: '0.1',
  price: '95000.00',
});

Field	Type	Required	Description
`address`	`string`	Yes	User’s wallet address
`provider`	`string`	Yes	Provider identifier
`market`	`MarketRef`	Yes	Target market (`{ marketId, categoryId }`)
`side`	`OrderSide`	Yes	Order direction
`type`	`OrderType`	Yes	`MARKET` or `LIMIT`. Stop and take-profit orders go through `takeProfit` / `stopLoss` or `placeTriggerOrder`
`size`	`string`	Yes	Order size
`price`	`string`	Yes	Limit price or slippage limit
`leverage`	`number`	No	At least 1 and ≤ the market’s max leverage; spot markets reject it. When provided, an `updateLeverage` step is always prepended and signed with the order. Omit it to leave the venue setting untouched
`marginMode`	`MarginMode`	No	Margin mode for the position. Hyperliquid: requires `leverage` alongside it (applied through the prepended `updateLeverage` step), and is rejected on spot markets. Ondo: `CROSS` only. Isolated-only markets reject `CROSS`. If omitted, the venue’s cross default applies, so send it on every order if your UI exposes a margin mode
`reduceOnly`	`boolean`	No	Only reduce position
`timeInForce`	`TimeInForce`	No	`GTC`, `IOC`, `POST_ONLY`. Support differs per provider; see Placing Orders
`expiresAt`	`string`	No	Future Unix ms timestamp. Honoured only by Lighter on `GTC` and `POST_ONLY` orders
`takeProfit`	`TriggerOrderInput`	No	Take profit trigger. Each leg has a required `type` (`MARKET` or `LIMIT`). See Trigger Orders
`stopLoss`	`TriggerOrderInput`	No	Stop loss trigger. Each leg has a required `type` (`MARKET` or `LIMIT`). See Trigger Orders

Returns: ExecuteActionResponse with results[] array, one entry per action (including a prepended updateLeverage).

cancelOrders

Cancel one or more orders. Auto-signs through the provider plugin.

const result = await perps.cancelOrders({
  provider: 'hyperliquid',
  address: userAddress,
  ids: ['12345678'],
});

Field	Type	Required	Description
`address`	`string`	Yes	User’s wallet address
`provider`	`string`	Yes	Provider identifier
`ids`	`string[]`	Yes	Order IDs to cancel. Venues whose ids are scoped per market (e.g. Lighter’s `order_index`) also accept the composite `"<market_id>:<order_id>"`.
`assetId`	`string`	No	Market context for per-market order ids — the order’s `market.id`

Returns: ExecuteActionResponse with results[] array. To cancel every open order in one action, use execute with ActionType.CANCEL_ALL_ORDERS (see Cancelling Orders).

modifyOrders

Modify orders in place. Auto-signs through the provider plugin.

const result = await perps.modifyOrders({
  provider: 'hyperliquid',
  address: userAddress,
  modifications: [{ id: '12345678', price: '94500.00', size: '0.1' }],
});

Field	Type	Required	Description
`provider`	`string`	Yes	Provider identifier
`address`	`string`	Yes	User’s wallet address
`modifications`	`ModifyOrderInput[]`	Yes	Modifications to apply. Supported fields differ per provider; see Modifying Orders

Returns: ExecuteActionResponse with results[] array.

placeTriggerOrder

Place standalone trigger orders (TP/SL on existing positions). Auto-signs with the provider’s SDK-managed credential.

import { OrderSide, OrderType } from '@lifi/perps-sdk';

const result = await perps.placeTriggerOrder({
  provider: 'hyperliquid',
  address: userAddress,
  market: { marketId: 'BTC', categoryId: 'hyperliquid' },
  side: OrderSide.SELL,
  takeProfit: { type: OrderType.MARKET, triggerPrice: '100000.00' },
  stopLoss: { type: OrderType.MARKET, triggerPrice: '90000.00' },
});

Field	Type	Required	Description
`provider`	`string`	Yes	Provider identifier
`address`	`string`	Yes	User’s wallet address
`market`	`MarketRef`	Yes	Target market (`{ marketId, categoryId }`)
`side`	`OrderSide`	Yes	Order side
`takeProfit`	`TriggerOrderInput`	No	Take profit trigger. Each leg has a required `type` (`MARKET` or `LIMIT`). See Trigger Orders
`stopLoss`	`TriggerOrderInput`	No	Stop loss trigger. Each leg has a required `type` (`MARKET` or `LIMIT`). See Trigger Orders

Returns: ExecuteActionResponse with results[] array.

placeTwapOrder

Place a TWAP parent order that executes over a fixed duration. Auto-signs with the provider’s SDK-managed credential.

import { OrderSide, isSubmittedOrAccepted } from '@lifi/perps-sdk';

const result = await perps.placeTwapOrder({
  provider: 'hyperliquid',
  address: userAddress,
  market: { marketId: 'BTC', categoryId: 'hyperliquid' },
  side: OrderSide.BUY,
  size: '1.5',
  durationSeconds: 1800,
});

for (const r of result.results) {
  if (isSubmittedOrAccepted(r)) {
    console.log(r.twapId);
  } else {
    console.error(r.status, r.errorCode, r.error);
  }
}

Field	Type	Required	Description
`provider`	`string`	Yes	Provider identifier
`address`	`string`	Yes	User’s wallet address
`market`	`MarketRef`	Yes	Target market (`{ marketId, categoryId }`)
`side`	`OrderSide`	Yes	Order direction
`size`	`string`	Yes	Total base-asset size executed across the TWAP’s lifetime
`durationSeconds`	`number`	Yes	Total execution window in seconds
`reduceOnly`	`boolean`	No	Only reduce the position
`randomize`	`boolean`	No	Hyperliquid extra — randomize each sub-order’s size by up to ±20%. Honoured only by providers that advertise it.
`frequencySeconds`	`number`	No	Ondo extra — interval between child orders in seconds. Honoured only by providers that advertise it.
`minPrice`	`string`	No	Ondo extra — lowest acceptable child-order price. Honoured only by providers that advertise it.
`maxPrice`	`string`	No	Ondo extra — highest acceptable child-order price. Honoured only by providers that advertise it.

Returns: ExecuteActionResponse with results[] array. A Submitted or Accepted result carries twapId — the provider-native identifier for the placed TWAP parent.

A provider only honours the extras it declares via its placeTwapOrder action’s params descriptors (GET /providers); other providers ignore them. See each provider’s trading page — Hyperliquid, Lighter, Ondo — for its extras and duration bounds.

cancelTwapOrder

Cancel a running TWAP parent order. Auto-signs with the provider’s SDK-managed credential.

const result = await perps.cancelTwapOrder({
  provider: 'hyperliquid',
  address: userAddress,
  market: { marketId: 'BTC', categoryId: 'hyperliquid' },
  twapId: '4521',
});

Field	Type	Required	Description
`provider`	`string`	Yes	Provider identifier
`address`	`string`	Yes	User’s wallet address
`market`	`MarketRef`	Yes	Target market — required by every provider’s cancel wire even where the TWAP id is globally unique
`twapId`	`string`	Yes	Provider-native TWAP identifier: Hyperliquid’s numeric id, Ondo’s `twap_`-prefixed id, or Lighter’s order index (scoped per market)

Returns: ExecuteActionResponse with results[] array.

updatePositionMargin

Adjust position margin. Auto-signs with the provider’s SDK-managed credential.

const result = await perps.updatePositionMargin({
  provider: 'hyperliquid',
  address: userAddress,
  market: { marketId: 'BTC', categoryId: 'hyperliquid' },
  action: 'add',
  amount: '500.00',
});

Field	Type	Required	Description
`provider`	`string`	Yes	Provider identifier
`address`	`string`	Yes	User’s wallet address
`market`	`MarketRef`	Yes	Target market (`{ marketId, categoryId }`)
`action`	`'add' \| 'remove'`	Yes	Add or remove margin
`amount`	`string`	Yes	Margin amount

Returns: ExecuteActionResponse with results[] array. See Position Margin for what each market allows and how much can be removed.

sendAsset

Move collateral between a provider’s categories (e.g. between perps and spot). This is a convenience wrapper over execute(SEND_ASSET) and follows the provider descriptor’s signer; Hyperliquid uses the user’s wallet.

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

const { assets } = await getAssets(client, { provider: 'hyperliquid' });
const usdcAsset = assets.find((a) => a.displaySymbol === 'USDC');

if (usdcAsset) {
  const result = await perps.sendAsset({
    provider: 'hyperliquid',
    address: userAddress,
    collateral: usdcAsset.id,
    sourceDex: 'hyperliquid',
    destinationDex: 'spot',
    amount: '100.00',
  });
}

On Hyperliquid the call is USER-signed, so the wallet must be on the typed-data domain chain (see setSwitchChain).

Field	Type	Required	Description
`provider`	`string`	Yes	Provider identifier
`address`	`Address`	Yes	User’s wallet address
`collateral`	`string`	Yes	Canonical `Asset.id` of the asset being moved (for Hyperliquid spot assets, the token index as a string) — never a display symbol
`sourceDex`	`string`	Yes	Category to move from. Hyperliquid: a category id from `provider.categories[].id` (`hyperliquid` is the main perps dex, then HIP-3 names such as `xyz`, and `spot`). Lighter: `perps` or `spot`
`destinationDex`	`string`	Yes	Category to move to. Same values as `sourceDex`
`amount`	`string`	Yes	Amount to move

Returns: ExecuteActionResponse with results[] array. A venue rejection does not throw. The venue’s balances can lag the transfer for a couple of seconds; re-read once after a short delay.

Generic action helper

The high-level methods above (placeOrder, cancelOrders, modifyOrders, placeTriggerOrder, placeTwapOrder, cancelTwapOrder, updatePositionMargin) are convenience wrappers around a single generic helper. Use it directly when an action does not have a dedicated wrapper.

execute

Auto-sign-and-submit for any action type. Mirrors placeOrder/modifyOrders/etc. but generic over ActionType. Internally builds the action, picks the signing pipeline from the descriptor’s signingMethod, signs, and submits in a single create → authorize → execute pass.

import { ActionType } from '@lifi/perps-types';

const result = await perps.execute({
  provider: 'hyperliquid',
  address: userAddress,
  action: ActionType.UPDATE_LEVERAGE,
  params: {
    market: { marketId: 'BTC', categoryId: 'hyperliquid' },
    leverage: 10,
  },
});

Field	Type	Required	Description
`provider`	`string`	Yes	Provider identifier
`address`	`string`	Yes	User’s wallet address
`action`	`ActionType`	Yes	Action type to execute
`params`	`ActionParamsMap[T]`	Yes	Action-specific params
`onProgress`	`(progress: SignActionProgress) => void`	No	Progress sink for on-chain legs (e.g. a native deposit’s `approve` then `deposit`); called as each leg is submitted and confirmed

Returns: ExecuteActionResponse with results[] array. execute does not throw on a venue refusal; check results[i].status.

SignActionProgress is { index, total, action, functionName, chainId, status, txHash }, where status is 'submitted' (wallet broadcast, hash known) then 'confirmed' (receipt mined) — emitted twice per on-chain leg, so a consumer can render a live per-transaction stepper.

Use execute for action types without dedicated wrappers — for example UPDATE_LEVERAGE, CANCEL_ALL_ORDERS or setup-choice actions. For trading actions with wrappers (placeOrder, cancelOrders, …), prefer the wrappers; they expose richer typed parameters.

buildAction

Build the action payloads for an action without signing or submitting. Typed wrapper around the createAction service (see Actions / createAction) and the natural counterpart to execute — use it when you need to inspect the steps, sign them in a custom flow, or hand them off across a process boundary before calling executeAction yourself.

import { ActionType } from '@lifi/perps-types';

const { actions } = await perps.buildAction(ActionType.UPDATE_LEVERAGE, {
  provider: 'hyperliquid',
  address: userAddress,
  params: {
    market: { marketId: 'BTC', categoryId: 'hyperliquid' },
    leverage: 10,
  },
});

Field	Type	Required	Description
`action`	`ActionType`	Yes	Action type to build (first positional argument)
`provider`	`string`	Yes	Provider identifier
`address`	`string`	Yes	User’s wallet address
`params`	`ActionParamsMap[T]`	Yes	Action-specific params

Returns: CreateActionResponse — { actions: ActionStep[] }. The SDK resolves the correct signer address (agent or user) for the given action type before delegating to createAction.

Setup

Account-setup steps (e.g. APPROVE_AGENT, APPROVE_BUILDER_FEE on Hyperliquid; REGISTER_API_KEY on Lighter) and user choices (Hyperliquid ACCOUNT_MODE, Lighter ACCOUNT_TYPE) are coordinated through the setup helpers. The high-level flow is described in Concepts / Action Pattern; the methods below are the lower-level building blocks. The SDK is the supported integration path for setup. It reads the account, decides which steps are satisfied, runs the steps in sequence order, and makes the client-side venue calls. For callers that use the API directly, see Integrating without the SDK.

checkSetup

Return the unsatisfied Provider.setup steps for this account as a flat list, together with the checklist a UI renders. Each ActionStep is self-describing — its action keys back to the provider’s setup step, which declares the signer, relay, and signing scheme — so no signer-role partition is exposed here.

const required = await perps.checkSetup({
  provider: 'hyperliquid',
  address: userAddress,
});

if (!required.isReady) {
  // required.setup: ActionStep[] — staged steps, ordered by descriptor sequence
  // required.checklist: every choice step and every USER-signed step, with its state
}

Field	Type	Required	Description
`provider`	`string`	Yes	Provider identifier
`address`	`string`	Yes	User’s wallet address

Returns: ProviderSetup — { accountExists: boolean; setup: ActionStep[]; isReady: boolean; checklist: SetupChecklistItem[] }.

accountExists reports whether the address already has account state with the provider.
setup holds the staged steps. Only a USER-signed step that is not a choice is staged.
isReady is true only when nothing is staged and every choice on checklist is satisfied.
checklist is the renderable onboarding list. Each item is { descriptor: SetupAction; satisfied: boolean; selected: SetupOption | null; currentValue: string | null }. Not-yet-applicable conditional steps (e.g. Hyperliquid’s revokeAgent, see Providers / Hyperliquid — Setup) are omitted rather than shown unsatisfied.

How `checkSetup()` treats each step

Step in `Provider.setup`	What `checkSetup()` does
Non-choice step, `signer: USER`	The SDK stages it in `setup` and lists it on `checklist`. Show it and sign it.
Non-choice step, `signer: SDK`	The SDK fulfils it with its own credentials, without a wallet prompt. It is not staged and not on `checklist`. Tell your users when such a step applies a referral code.
Choice step (`options` is an array)	The SDK lists it on `checklist` with `selected`, the option that matches the current account value. The SDK never stages it as a signable action, whatever its `signer`.

A choice is never executed by the SDK on its own. The option with default: true is only the recommended option, which a UI can pre-select. An unsatisfied choice keeps isReady false, and nothing changes until you pass an option to executeProviderOption. currentValue holds the raw venue value as the venue names it, for example plus or premium for the Lighter account tier. Read the result in three states:

State	Meaning	Next step
`accountExists === false`	The address has no venue account. `setup` is empty and `isReady` is `false`	Fund the account first (see `getDepositFlow`), then call `checkSetup` again
`isReady === false`	Steps are outstanding	Run the steps in `setup`, then call `checkSetup` again
`isReady === true`	Setup is complete	Trade

isReady can stay false with an empty setup while an SDK-signed step is still pending; call checkSetup again.

checkSetup is not a pure read. It stages USER steps (allocating their nonces) and executes pending SDK-signed steps, such as setReferrer, without a wallet prompt. Each call makes several venue and backend requests. Do not call it concurrently with a signing flow, on window focus or in a tight poll: a second call can invalidate a step that is being signed. Re-run it once after each executed step.

buildProviderSetup

Build the unsigned setup ActionSteps still outstanding for an account, ordered by descriptor sequence, without signing or submitting. The backend filters out already-satisfied setup — same filtering as checkSetup().setup — but the response carries only { actions }, without checkSetup’s surrounding accountExists, isReady, and checklist metadata. Like checkSetup().setup, it stages only USER-signed steps that are not choices.

const { actions } = await perps.buildProviderSetup({
  provider: 'hyperliquid',
  address: userAddress,
});

Field	Type	Required	Description
`provider`	`string`	Yes	Provider identifier
`address`	`string`	Yes	User’s wallet address

Returns: CreateActionResponse — { actions: ActionStep[] }.

executeProviderSetupAction

Sign and submit one pre-staged setup ActionStep end-to-end. The caller obtains the step and the checklist from the same checkSetup call, without a refetch. The checklist is a snapshot: it does not change when a step runs. Call checkSetup again after each step, and handle the first unsatisfied item of the checklist each time. A choice step blocks the steps after it, so the loop executes a choice through executeProviderOption when it reaches one:

const provider = 'lighter';
let required = await perps.checkSetup({ provider, address: userAddress });

while (required.accountExists && !required.isReady) {
  const item = required.checklist.find((entry) => !entry.satisfied);
  if (!item) break;

  const { options } = item.descriptor;
  if (options !== null) {
    // Show the options and let the user choose. This example takes the recommended one.
    const option = options.find((o) => o.default === true) ?? options[0];
    await perps.executeProviderOption({
      provider,
      address: userAddress,
      option,
    });
  } else {
    const step = required.setup.find((s) => s.action === item.descriptor.type);
    if (!step) break;
    await perps.executeProviderSetupAction({
      provider,
      address: userAddress,
      step,
      checklist: required.checklist,
    });
  }

  required = await perps.checkSetup({ provider, address: userAddress });
}

Field	Type	Required	Description
`provider`	`string`	Yes	Provider identifier
`address`	`string`	Yes	User’s wallet address
`step`	`ActionStep`	Yes	A single step from `checkSetup().setup`
`checklist`	`SetupChecklistItem[]`	Yes	The `checklist` from the same `checkSetup()` result

Returns: Promise<ExecuteActionResponse>. A Failed or Indeterminate step is a result in the report, not an exception. Throws: PerpsError (SDKError) when the step’s action is not in the provider’s setup, when a step with a lower sequence on checklist is still unsatisfied, or when signing or submission fails before any result is known. PerpsExecutionError carries the known results when a later stage fails. A choice counts as such a step. Satisfy the choice first, with executeProviderOption.

Requires the user wallet, set with perps.setUserWallet(walletClient), for any step that requires the user’s L1 wallet — that includes EIP-712, EVM-tx, and Lighter’s REGISTER_API_KEY (which signs the EIP-191 message embedded in the WASM blob).

executeProviderOption

Execute the option the user chose for a choice step (for example Hyperliquid accountMode or Lighter accountType) end-to-end. The option is a SetupOption: it carries its own bound type and params. Dispatches through the same pipeline as execute, but an option change is a single mandatory action. A Failed or Indeterminate result is returned in the report and does not throw. Read the status before you treat the option as applied.

import { ActionType } from '@lifi/perps-types';

const item = required.checklist.find(
  (entry) => entry.descriptor.type === ActionType.ACCOUNT_TYPE,
);
const option = item?.descriptor.options?.find((o) => o.title === 'Premium');

if (option) {
  await perps.executeProviderOption({
    provider: 'lighter',
    address: userAddress,
    option,
  });
}

Field	Type	Required	Description
`provider`	`string`	Yes	Provider identifier
`address`	`string`	Yes	User’s wallet address
`option`	`SetupOption`	Yes	The chosen option, taken from `SetupAction.options`

Returns: Promise<ExecuteActionResponse>. Read results[i].status: a refusal is a Failed result, not an exception.

executeProviderRevoke

Undo a satisfied setup step by executing its revoke action. The SDK creates, signs, and submits the action, and signs it with the descriptor of that action from Provider.actions. The step is unsatisfied afterwards, so it stages again on the next checkSetup().

import { ActionType } from '@lifi/perps-types';

const item = required.checklist.find(
  (entry) => entry.descriptor.type === ActionType.APPROVE_BUILDER_FEE,
);

if (item?.satisfied && item.descriptor.revoke !== null) {
  await perps.executeProviderRevoke({
    provider: 'hyperliquid',
    address: userAddress,
    step: item.descriptor,
  });
}

Field	Type	Required	Description
`provider`	`string`	Yes	Provider identifier
`address`	`string`	Yes	User’s wallet address
`step`	`SetupAction`	Yes	A setup descriptor whose `revoke` is not `null`

Returns: Promise<ExecuteActionResponse>. Throws: PerpsError (SDKError) when step.revoke is null, or when createAction stages nothing to revoke. A refused or Indeterminate revoke is a result in the report. Otherwise it throws the errors that executeProviderOption throws.

Order and position reads

These PerpsClient methods read directly from the venue through the registered provider plugin. They take the same parameters as the getOrders and getOrder services.

const { orders } = await perps.getOrders({
  provider: 'hyperliquid',
  address: userAddress,
});

const order = await perps.getOrder({
  provider: 'hyperliquid',
  address: userAddress,
  id: '12345678',
});

getOrders returns { orders: Order[] } (Order = RegularOrder | TriggerOrder | TwapOrder, discriminated on type). getOrder returns one Order.

getPositionRemovableMargin

Return the margin you can remove from an already-fetched Position, as a decimal string; undefined when the position has no individual margin adjustment and '0' when nothing is removable. See Position Margin.

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

const { positions } = await getPositions(perps.client, {
  provider: 'hyperliquid',
  address: userAddress,
});
const removable = perps.getPositionRemovableMargin(positions[0]);

client

perps.client is the underlying PerpsSDKClient. Pass it to service functions such as getMarkets, getPositions and getTermsAcceptance, and to PerpsWsClient.

App-level meta actions

These three methods dispatch provider-independent app-level actions — LI.FI terms acceptance and the internal referral code — using the META_PROVIDER sentinel instead of a real provider key. They are always signed as EIP-712 typed data with the configured user wallet. See SDK / Actions — App-level onboarding for the full dispatch model.

submitOnboarding

Accept the current terms and, when a code is supplied and the backend accepts it, attach that internal referral code — in one signature.

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

const terms = await getTermsAcceptance(perps.client, userAddress);

await perps.submitOnboarding({
  address: userAddress,
  termsVersion: terms.termsVersion,
  referralCode: 'FRIEND123',
});

Field	Type	Required	Description
`address`	`Address`	Yes	User’s wallet address
`termsVersion`	`string`	No	Terms-of-service version being accepted; relayed verbatim to the backend. Check `getTermsAcceptance` for the current version.
`referralCode`	`string`	No	Candidate referral code as captured from the user; the backend normalizes it

Returns: ExecuteActionResponse — resolves to { results: [] } when the backend requires no consent from this address.

createReferralCode

Reserve the shareable internal referral code address owns.

await perps.createReferralCode({ address: userAddress, code: 'MYCODE' });

Field	Type	Required	Description
`address`	`Address`	Yes	User’s wallet address
`code`	`string`	Yes	Desired code. The backend does not generate one — a request that omits `code` is rejected.

The address must have reached the backend’s executed-notional threshold before it can create a code, and an address owns exactly one permanent code. Returns: ExecuteActionResponse.

executeMetaAction

Low-level entry point both submitOnboarding and createReferralCode call. Use it directly for META_ACCEPT_TERMS or any future meta action without a dedicated wrapper.

import { ActionType, getTermsAcceptance } from '@lifi/perps-sdk';

const terms = await getTermsAcceptance(perps.client, userAddress);

await perps.executeMetaAction({
  address: userAddress,
  action: ActionType.META_ACCEPT_TERMS,
  params: { termsVersion: terms.termsVersion },
});

Field	Type	Required	Description
`address`	`Address`	Yes	User’s wallet address
`action`	`MetaActionType`	Yes	`META_ACCEPT_TERMS`, `META_ONBOARD`, or `META_CREATE_REFERRAL_CODE`
`params`	`ActionParamsMap[T]`	Yes	Action-specific params

Returns: ExecuteActionResponse. Throws PerpsError when no user wallet is configured, when the backend returns more than one step or a non-EIP-712 step, or when the submitted step reports a failed result. A wallet signature refusal propagates as the wallet’s own error. API Reference: POST /createAction · /executeAction

​setUserWallet

​setSwitchChain

​getMarketSettings

​placeOrder

​cancelOrders

​modifyOrders

​placeTriggerOrder

​placeTwapOrder

​cancelTwapOrder

​updatePositionMargin

​sendAsset

​Generic action helper

​execute

​buildAction

​Setup

​checkSetup

​How checkSetup() treats each step

​buildProviderSetup

​executeProviderSetupAction

​executeProviderOption

​executeProviderRevoke

​Order and position reads

​getPositionRemovableMargin

​client

​App-level meta actions

​submitOnboarding

​createReferralCode

​executeMetaAction

setUserWallet

setSwitchChain

getMarketSettings

placeOrder

cancelOrders

modifyOrders

placeTriggerOrder

placeTwapOrder

cancelTwapOrder

updatePositionMargin

sendAsset

Generic action helper

execute

buildAction

Setup

checkSetup

How `checkSetup()` treats each step

buildProviderSetup

executeProviderSetupAction

executeProviderOption

executeProviderRevoke

Order and position reads

getPositionRemovableMargin

client

App-level meta actions

submitOnboarding

createReferralCode

executeMetaAction