PerpsClient Methods

Complete reference for all PerpsClient trading methods

Complete reference for PerpsClient trading and setup methods. Authorization follows each provider’s ProviderAction.signers 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.

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 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. Some setup and deposit actions must be signed on a specific chain; when the user’s wallet is on the wrong one, the SDK calls this hook with the target chainId and expects it to return a wallet client on that chain (or undefined to abort). 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' },
});

if (settings) {
  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 | undefined — { marginMode, leverage }, or undefined when the provider exposes no readable market setting or does not implement the optional capability.

---

placeOrder

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

const result = await perps.placeOrder(params);

Field	Type	Required	Description
address	string	Yes	User’s wallet address
provider	string	Yes	Provider identifier
market	MarketRef	Yes	Target market ({ marketId, categoryId })
side	'BUY' | 'SELL'	Yes	Order direction
type	OrderType	Yes	Order type: MARKET, LIMIT, STOP_MARKET, STOP_LIMIT, TAKE_PROFIT_MARKET, TAKE_PROFIT_LIMIT, TRIGGER_ONLY
size	string	Yes	Order size
price	string	Yes	Limit price or slippage limit
leverage	number	No	Leverage to set (generates an updateLeverage step if it differs from the current setting)
marginMode	MarginMode	No	Margin mode for the position. Omitted falls back to the provider’s default (currently CROSS).
reduceOnly	boolean	No	Only reduce position
timeInForce	string	No	GTC, IOC, POST_ONLY, GTT
expiresAt	string	No	Unix ms timestamp expiry for GTT (must be in the future)
takeProfit	TriggerOrderInput	No	Take profit trigger
stopLoss	TriggerOrderInput	No	Stop loss trigger

Returns: ExecuteActionResponse with results[] array.

---

cancelOrders

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

const result = await perps.cancelOrders(params);

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.

---

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' }],
});

Field	Type	Required	Description
provider	string	Yes	Provider identifier
address	string	Yes	User’s wallet address
modifications	ModifyOrderInput[]	Yes	Modifications to apply

Returns: ExecuteActionResponse with results[] array.

---

placeTriggerOrder

Place standalone trigger orders (TP/SL on existing positions). Auto-signs with the agent.

const result = await perps.placeTriggerOrder({
  provider: 'hyperliquid',
  address: userAddress,
  market: { marketId: 'BTC', categoryId: 'hyperliquid' },
  side: 'SELL',
  takeProfit: { triggerPrice: '100000.00' },
  stopLoss: { 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	'BUY' | 'SELL'	Yes	Order side
takeProfit	TriggerOrderInput	No	Take profit trigger
stopLoss	TriggerOrderInput	No	Stop loss trigger

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.

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

console.log(result.results[0].twapId);

Field	Type	Required	Description
provider	string	Yes	Provider identifier
address	string	Yes	User’s wallet address
market	MarketRef	Yes	Target market ({ marketId, categoryId })
side	'BUY' | 'SELL'	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 sub-order timing within the window. 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 successful 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 agent.

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.

---

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.

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

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

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 id to move from
destinationDex	string	Yes	Category id to move to
amount	string	Yes	Amount to move

Returns: ExecuteActionResponse with results[] array.

---

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 correct signing pipeline (EIP-712, WASM blob, or EVM tx) from the provider’s descriptor, signs, and submits in a single create→sign→submit 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.

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 or provider-specific account-configuration 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 actions (e.g. APPROVE_AGENT, APPROVE_BUILDER_FEE on Hyperliquid; REGISTER_API_KEY on Lighter) 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.

checkSetup

Return the unsatisfied entries on the provider’s setup descriptors for this account as a flat list. Each ActionStep is self-describing — its action keys back to the provider’s setup descriptor, which declares the step’s signer 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[] — outstanding steps, ordered by descriptor sequence
}

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. checklist is the renderable onboarding list: every USER-signed setup descriptor paired with its satisfied state ({ descriptor: ProviderAction; satisfied: boolean }), with not-yet-applicable conditional descriptors (e.g. Hyperliquid’s revokeAgent, see Providers / Hyperliquid — Setup) omitted rather than shown unsatisfied.

Provider.options descriptors are never returned here — options are post-setup tunables and never gate trading. Option state is surfaced separately via getAccount().settings.

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.

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 is expected to have already obtained the step from a prior checkSetup call (no refetch). Run the outstanding steps in descriptor order:

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

for (const step of required.setup) {
  await perps.executeProviderSetupAction({
    provider: 'lighter',
    address: userAddress,
    step,
  });
}

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

Returns: Promise<void>.

Requires the user wallet to be set via setUserWallet (or passed at construction) 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

Sign and submit a single Provider.options change (a post-setup tunable such as Hyperliquid accountMode or Lighter accountType) end-to-end. Dispatches through the same pipeline as execute, but an option change is a single mandatory action: a per-action success: false throws a PerpsError, using that result’s errorCode when the backend classified the failure and falling back to PerpsErrorCode.ExchangeRejected otherwise, rather than being silently dropped.

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

await perps.executeProviderOption({
  provider: 'hyperliquid',
  address: userAddress,
  action: ActionType.ACCOUNT_MODE,
  params: { mode: 'unifiedAccount' },
});

Field	Type	Required	Description
provider	string	Yes	Provider identifier
address	string	Yes	User’s wallet address
action	ActionType	Yes	The options action to apply (e.g. ACCOUNT_MODE, ACCOUNT_TYPE)
params	ActionParamsMap[T]	Yes	The selected option value

Returns: Promise<void> — resolves on success, throws PerpsError on venue rejection.

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.

await perps.submitOnboarding({
  address: userAddress,
  termsVersion: currentTermsVersion,
  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.

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 } from '@lifi/perps-types';

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

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