Actions

The create -> sign -> execute pattern for all mutating operations

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 also flow through these endpoints, but the SDK exposes higher-level helpers (withdraw, checkSetup / executeProviderSetup) that should be preferred.

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 (Hyperliquid and other EVM dexes), a WASM-signer blob (Lighter), or an EVM transaction (e.g. Lighter deposit).
2. Sign — sign each step with the appropriate signer for its shape. For trade actions this is the SDK-managed agent (the high-level methods do this for you). For setup actions, withdrawals, and on-chain deposits it is the user’s L1 wallet. Use signProviderSetupAction to dispatch by step shape without embedding per-method logic.
3. Execute — call executeAction() with the signed payloads. Returns success/failure for each action.

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	Record<string, unknown>	Transaction parameters (chainId, to, functionName, args, abi) submitted by the SDK

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.

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

EvmTxSignedActionStep:

Field	Type	Description
action	ActionType	Action type from the create response
txParams	Record<string, unknown>	Original txParams from createAction
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 (for placeOrder and placeTriggerOrder)
error	string?	Error message if failed

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
approveBuilderFee	Setup	Approve builder fee
accountMode	Options	Switch account operating mode (e.g. Hyperliquid abstraction variant, Lighter UTA/Simple). Accepts either signer; the backend dispatches to the right typed-data builder based on which key signs.
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 API-key slot
placeOrder	Trading	Place a new order
placeTriggerOrder	Trading	Place standalone TP/SL
cancelOrder	Trading	Cancel orders by ID
cancelAllOrders	Trading	Cancel every open order on the account
modifyOrder	Trading	Modify existing orders
updateLeverage	Trading	Change leverage (and optionally margin mode) for an asset
updatePositionMargin	Trading	Add/remove margin on a position
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 sub-exchanges

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