Actions

The provider-specific create -> authorize -> execute action flow

All mutating operations — trading, withdrawals, leverage changes, position margin, account setup — flow through the same two service functions: createAction and executeAction.

For trading actions, the Trading pages document the convenience wrappers (placeOrder, cancelOrders, etc.) that handle createAction, agent-signing, and executeAction automatically. Those wrappers are the supported public surface for trade dispatch — createAction/executeAction are documented here for completeness and for action types that don’t have a dedicated wrapper. Withdrawals and account setup use the same authorization model, but the SDK exposes higher-level helpers (withdraw, checkSetup / executeProviderSetupAction) that should be preferred. Session-only actions execute directly through the provider plugin and intentionally skip executeAction.

Pattern

createAction → actions[] → sign each step → executeAction → results[]

1. Create — call createAction() with the action type and params. Returns one or more ActionStep payloads. Each step’s shape depends on the action’s signingMethod: EIP-712 typed data, a WASM-signer blob, an EVM transaction, an HMAC request, a SIWE challenge, or a client-only session marker.
2. Authorize — let the provider plugin sign or execute each step according to ProviderAction.signers and signingMethod. USER means a user-owned authorization path (usually the wallet, or a client-held provider session for session steps); SDK means the provider plugin completes the step internally. Use executeProviderSetupAction for setup steps instead of embedding scheme-specific logic.
3. Execute — call executeAction() with signed EIP-712, WASM, EVM, HMAC, or SIWE payloads. A session step is completed client-side by the plugin and produces no signed step to submit.

createAction

Build action payloads for signing.

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

const { actions } = await createAction(client, {
  provider: 'hyperliquid',
  address: userAddress,
  action: 'placeOrder',
  params: {
    market: { marketId: 'BTC', categoryId: 'hyperliquid' },
    side: 'BUY',
    type: 'LIMIT',
    size: '0.1',
    price: '94000.00',
    timeInForce: 'GTC',
  },
});

// actions: ActionStep[] — one or more payloads to sign

Parameters

Parameter	Type	Required	Description
client	PerpsSDKClient	Yes	SDK client
params.provider	string	Yes	Provider identifier
params.address	string	Yes	User’s wallet address (account owner)
params.signerAddress	string	No	Address that will sign. For agent-signed trade actions this is the agent address; for user-signed setup actions it defaults to address.
params.action	ActionType	Yes	Action type (see Action Types)
params.params	object	Yes	Action-specific parameters (see Actions API)
options	SDKRequestOptions	No	Request options

Returns

CreateActionResponse — { actions: ActionStep[] }.

ActionStep is a discriminated union by structural shape — the SDK dispatches to the correct signer based on which key is present. The variant that comes back is determined by the action’s signingMethod on the provider descriptor (see SigningMethod).

Eip712ActionStep — EIP-712 typed-data flow (Hyperliquid; most actions):

Field	Type	Description
action	ActionType	Action type
typedData	PerpsTypedData	EIP-712 typed data to sign

WasmBlobActionStep — WASM signer flow (Lighter):

Field	Type	Description
action	ActionType	Action type
wasmSignParams	Record<string, unknown>	Parameters fed to the provider’s WASM signer

EvmTxActionStep — on-chain EVM transaction (e.g. Lighter deposit):

Field	Type	Description
action	ActionType	Action type
txParams	EvmCall	Transaction parameters (chainId, to, functionName, args, abi) submitted by the SDK — see EvmCall

HmacActionStep — provider request signed SDK-side with a client-held API key:

Field	Type	Description
action	ActionType	Action type
request	{ method, path, body? }	Exact venue-relative request; body is pre-serialized because those bytes are signed

SiweActionStep — ERC-4361 login challenge:

Field	Type	Description
action	ActionType	Action type
siwe	{ challengeId, message }	Backend-issued challenge and exact message for personal_sign

SessionActionStep — provider-session marker completed client-side, not sent to executeAction. Ondo’s createDepositAddress carries a public { network: 'ethereum', symbol: 'USDC', depositDestination: { wallet: 'margin' } } policy marker; acceptProviderTerms and registerApiKey use an empty marker (session: {}). A session-signed action can also be wire-shaped as a request-bearing step instead of a marker — Ondo’s setReferrer carries a real { method, path, body } request that the SDK submits directly with the session credential rather than HMAC-signing it.

A single createAction call may return multiple actions. For example, placeOrder with a leverage param different from the current setting returns both an updateLeverage and a placeOrder step.

EvmCall

The txParams on the EVM-transaction step variants is an EvmCall:

Field	Type	Description
chainId	number	Chain the transaction targets
to	string	Contract address to call
functionName	string	Name of the contract function to invoke
args	readonly unknown[]	Arguments passed to the function
abi	readonly string[]	Human-readable function signatures for encoding the call

executeAction

Submit signed action payloads.

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

const result = await executeAction(client, {
  provider: 'hyperliquid',
  address: userAddress,
  action: 'placeOrder',
  actions: signedActions,
});

for (const r of result.results) {
  console.log(r.action, r.success, r.orderId);
}

Parameters

Parameter	Type	Required	Description
client	PerpsSDKClient	Yes	SDK client
params.provider	string	Yes	Provider identifier
params.address	string	Yes	User’s wallet address (account owner)
params.signerAddress	string	No	Address that signed. For agent-signed actions this is the agent address; otherwise defaults to address.
params.action	ActionType	Yes	Action type from the create request
params.actions	SignedActionStep[]	Yes	Signed payloads from createAction
options	SDKRequestOptions	No	Request options

SignedActionStep is a discriminated union that mirrors ActionStep — each variant carries the original payload plus its signed artefact.

Eip712SignedActionStep:

Field	Type	Description
action	ActionType	Action type from the create response
typedData	PerpsTypedData	Original typedData from createAction
signature	Hex	Signer’s signature of the typedData

WasmBlobSignedActionStep:

Field	Type	Description
action	ActionType	Action type from the create response
wasmSignParams	Record<string, unknown>	Original wasmSignParams from createAction
signedTx	{ txType, txInfo, txHash }	Output of the provider’s WASM signer
clientOrderIndex	string (optional)	Provider-native order reference, as a decimal string. Present only when the step’s action places an order. It is an additional reference, not an Order.orderId — the venue assigns that separately.

EvmTxSignedActionStep:

Field	Type	Description
action	ActionType	Action type from the create response
txParams	EvmCall	Original txParams from createAction — see EvmCall
txHash	string	On-chain transaction hash after the SDK has broadcast the tx

Returns

ExecuteActionResponse — { results: ActionResult[] }:

Each ActionResult:

Field	Type	Description
action	ActionType	Action type
success	boolean	Whether the action was accepted
orderId	string?	Order ID on a successful order action
twapId	string?	Provider-native identifier for a placed TWAP parent order
txHash	string?	Venue transaction hash when known at submission time
explorerLink	string?	Fully resolved explorer URL for txHash, when configured
error	string?	Error message on a failed result
errorCode	PerpsErrorCode?	Structured failure classification, when provided

Action Types

All action types from the provider’s setup, options, and actions arrays can be used with createAction/executeAction:

Action	Category	Description
approveAgent	Setup	Authorize an agent wallet
revokeAgent	Setup	Deregister an existing agent to free an agent slot (Hyperliquid). Conditional — staged only when every named agent slot on the account is already taken.
approveBuilderFee	Setup	Approve builder fee
approveIntegrator	Setup	Authorize LI.FI’s integrator account to collect fees, up to a max rate (Lighter). No params.
setReferrer	Setup	Register the account’s referrer code (Hyperliquid, Lighter, and Ondo)
accountMode	Options	Switch account operating mode (e.g. Hyperliquid abstraction variant, Lighter UTA/Simple). Read the provider descriptor for its allowed signer and values.
accountType	Options	Switch account fee/latency tier (e.g. Lighter standard/premium). Omitted by providers with no tiering.
registerApiKey	Setup	Register or rotate a Lighter signing-key slot
approveReadOnlyToken	Setup	Approve a read-only auth token (Lighter)
siweLogin	Setup	Sign in to a provider session with an ERC-4361 challenge
createDepositAddress	Setup	Provision the provider-managed deposit address; the session step carries the fixed network/asset/destination policy
acceptProviderTerms	Setup	Accept venue-specific terms through the provider session
placeOrder	Trading	Place a new order
placeTriggerOrder	Trading	Place standalone TP/SL
placeTwapOrder	Trading	Place a TWAP parent order that executes over a fixed duration
cancelOrder	Trading	Cancel orders by ID
cancelAllOrders	Trading	Cancel every open order on the account
cancelTwapOrder	Trading	Cancel a running TWAP parent order
modifyOrder	Trading	Modify existing orders
updateLeverage	Trading	Change leverage (and optionally margin mode) for an asset
updatePositionMargin	Trading	Add/remove margin on a position
updateAssetCollateral	Trading	Opt a spot asset in/out of the cross-margin collateral pool (Lighter unified account)
withdrawal	Transfer	Withdraw funds to L1
deposit	Transfer	Fund the account via an L1 bridge transaction
transfer	Transfer	Internal balance transfer (provider-specific)
sendAsset	Transfer	Move collateral between a provider’s venues (Hyperliquid sub-DEXes, or Lighter perps ↔ spot routes)

| metaAcceptTerms | Meta | Accept the current app-wide LI.FI terms of service. Provider-independent (see App-level onboarding). | | metaOnboard | Meta | Accept the current app-wide terms and, optionally, attach an internal referral code, in one signature. Provider-independent (see App-level onboarding). | | metaCreateReferralCode | Meta | Reserve the shareable internal referral code an address owns. Provider-independent (see App-level onboarding). |

For parameter schemas per action type, see Actions API. For the high-level convenience wrappers that handle agent signing automatically, see SDK / Trading.

API Reference: POST /createAction, POST /executeAction

App-level onboarding

The three Meta actions above are provider-independent: the SDK sends them with the META_PROVIDER ('meta') sentinel instead of a real provider key, so the backend dispatches them without resolving a venue plugin. They carry no ProviderAction descriptor and are always signed as EIP-712 typed data with the end-user’s wallet — never with a provider’s agent, native key, or session credential.

PerpsClient exposes three matching methods:

Method	Action	Description
submitOnboarding(params)	metaOnboard	Accepts the current terms and, when a code is supplied and the backend accepts it, attaches that internal referral code — in one signature. params: { address, termsVersion?, referralCode? }. Resolves to { results: [] } when the backend requires no consent from this address.
createReferralCode(params)	metaCreateReferralCode	Reserves the shareable internal referral code address owns. params: { address, code } — code is required; the backend does not generate one.
executeMetaAction(params)	Any MetaActionType	Low-level entry point both wrappers call. params: { address, action, params }.

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

const client = new PerpsClient({ apiKey: 'your-api-key' });
client.setUserWallet(walletClient);

// Accept the current terms and attach a referral code in one signature
await client.submitOnboarding({
  address: userAddress,
  termsVersion: currentTermsVersion,
  referralCode: 'FRIEND123',
});

// Reserve a shareable referral code for this address
await client.createReferralCode({ address: userAddress, code: 'MYCODE' });

All three methods throw 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.

Use getTermsAcceptance to check the current terms version and whether an address has already accepted it before calling submitOnboarding.