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[] → authorize 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.signer and signingMethod. USER means the user’s wallet or consent must act (usually the wallet, or a client-held provider session for session steps); SDK means the SDK fulfils the step with its own credentials. Use executeProviderSetupAction for setup steps instead of embedding scheme-specific logic.
3. Execute — call executeAction() with signed EIP-712, WASM, EVM, or HMAC payloads. session and SIWE steps are completed client-side by the provider plugin and never sent: they produce no signed step to submit, and /executeAction rejects siweLogin.

Every non-meta createAction and executeAction call fails with 401 / 2012 (TermsNotAccepted) until the address has accepted the current terms version. Only meta actions are exempt. Call getTermsAcceptance, then submitOnboarding, before any setup, trading, or withdrawal call, and again after a terms-version change.

​

createAction

Build action payloads for signing.

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

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

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

​

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. The provider plugin completes it client-side; it is never sent to executeAction:

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, registerApiKey, and addWithdrawalAddress 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.

On Hyperliquid, placeOrder with a leverage param always returns an updateLeverage step ahead of the placeOrder step; the SDK never compares leverage with the current setting. Omit leverage to leave the venue setting untouched.

​

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, ActionType, UserActionStatus, type SignedActionStep } from '@lifi/perps-sdk';

// Produced by the authorize step
declare const signedActions: SignedActionStep[];

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

for (const r of result.results) {
  switch (r.status) {
    case UserActionStatus.Submitted:
    case UserActionStatus.Accepted:
      console.log(r.action, r.orderId);
      break;
    case UserActionStatus.Indeterminate:
      // The step may have taken effect. Read the account state before you submit again.
      console.warn(r.action, r.errorCode, r.error);
      break;
    case UserActionStatus.Failed:
      console.error(r.action, r.errorCode, r.error);
      break;
  }
}

executeAction is the HTTP call. It resolves with the backend’s 202 report and does not throw for a failed or indeterminate step. A request or transport error throws. See Execution reports.

​

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

HmacSignedActionStep:

Field	Type	Description
action	ActionType	Action type from the create response
request	{ method, path, body? }	Original request from createAction, byte-for-byte
hmac.keyId	string	Identifier of the client-held API key
hmac.timestampMs	number	Sign-time Unix timestamp in milliseconds. It is part of the signed message; Ondo enforces a 30-second window.
hmac.signature	string	HMAC computed SDK-side

SiweSignedActionStep ({ action, siwe, signature }) exists in the SignedActionStep union, but the SDK never submits it: siweLogin is completed client-side and /executeAction rejects it.

​

Returns

ExecuteActionResponse — { results: ActionResult[] }:

Each ActionResult:

Field	Type	Description
action	ActionType	Action type
status	UserActionStatus	Submitted, Accepted, Indeterminate or Failed. There is no success field.
orderId	string?	Order ID when the step placed an order
twapId	string?	Provider-native identifier for a placed TWAP parent order
txHash	string?	Venue transaction hash, present only where the venue’s hash is known at submission time
explorerLink	string?	Fully resolved explorer URL for txHash, when configured
error	string?	Set unless status is Submitted or Accepted. Every Indeterminate error ends with CHECK_ACCOUNT_BEFORE_RETRY_TEXT.
errorCode	PerpsErrorCode?	The cause of the failure or uncertainty, for example TimeoutError, when classified

​

Execution reports

ExecuteActionResponse.results is an execution report: one ActionResult for each step that the backend attempted, in execution order. @lifi/perps-types exports UserActionStatus with five values, and @lifi/perps-sdk exports isSubmittedOrAccepted(result).

UserActionStatus	Value	In a result?	Meaning
Created	created	No	An unsigned intent. Nothing went to the venue. A step that was not attempted has no result.
Submitted	submitted	Yes	The venue acknowledged the send. The acknowledgement is not proof, and the backend verifies the step later.
Accepted	accepted	Yes	The venue provably took and applied the step. Ondo can return it in the response.
Indeterminate	indeterminate	Yes	The send started and the venue gave no clear answer. The step can have taken effect. Read the account state before you submit again.
Failed	failed	Yes	The venue refused the step, or a check failed before the backend sent it. Nothing was applied.

Three axes are separate:

• HTTP status. 202 means that the backend processed the request. It does not mean that the venue accepted a step.
• Action status. result.status says how far each step went.
• Error cause. result.errorCode and result.error say why a step failed or is uncertain.

What the report holds:

• Execution stops at the first step that is Failed or Indeterminate. The later steps are not attempted and have no result.
• Every member of an attempted atomic batch has its own result. Lighter sends an order and its trigger orders as one batch.
• Two steps with the same action keep two results. Do not key the results by action.
• Results of earlier acknowledged steps stay in the report after a later step fails.
• For a client-executed step, the report holds the SDK result before the backend results. Lighter token-authenticated venue calls and confirmed EVM legs are examples.

Handle every result. The first result does not stand for the report, results.every(isSubmittedOrAccepted) hides the cause of a stop, and a blind retry can repeat an order that the venue already took:

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

const { results } = await perps.placeOrder({ /* ... */ });

for (const result of results) {
  switch (result.status) {
    case UserActionStatus.Submitted:
    case UserActionStatus.Accepted:
      // This step was acknowledged. result.orderId is set when the step placed an order.
      break;
    case UserActionStatus.Indeterminate:
      // The step may have taken effect. Show result.error and read the account state.
      break;
    case UserActionStatus.Failed:
      // The step was refused. result.error and result.errorCode say why.
      break;
  }
}

Two cases look alike, and they are not the same:

• A returned result with status Failed is a confirmed refusal. The errorCode is the venue or LI.FI classification.
• A thrown error is a request, signing or transport failure with no report. The SDK did not get a result for it. See Error Handling.

When a later stage throws after some results are known, for example the explorer-link step or the onExecuteResults callback, the SDK throws PerpsExecutionError. Its response.results holds every result known at that point, and cause holds the original error. If no result is known, the original error propagates unchanged.

The Submitted status does not mean that the SDK pushes later verification updates to your code. Track the outcome with the account reads, for example Order Status.

​

Setup, options and revoke

executeProviderSetupAction, executeProviderOption and executeProviderRevoke return Promise<ExecuteActionResponse>. They return the report and do not return void. They do not throw for a Failed or Indeterminate step, so read status on each result. They throw PerpsError for the cases in their method reference, and PerpsExecutionError when a later stage fails after a result is known. submitOnboarding, createReferralCode and executeMetaAction follow the same rule.

PerpsProviderPlugin.signActions returns { signed, executed }. executed holds the results of steps that the plugin executed on the client. The client puts them in the report before the executeAction results, and it submits signed only when every executed result is Submitted or Accepted.

​

Release and migration

The status contract is a coordinated breaking release. It replaces the success boolean on ActionResult.

Before	After
result.success === true	result.status is Submitted or Accepted. Use isSubmittedOrAccepted(result) for one result.
result.success === false	result.status is Failed or Indeterminate. Handle the two values differently.
ActionResult is a union on success	ActionResult is one flat type. error is set unless the status is Submitted or Accepted.
Read the first failed result and stop	Read every result.
executeProviderSetupAction, executeProviderOption, executeProviderRevoke return void and throw on a failed result	They return the report. Read status.

Release requirements:

• Install matching versions of @lifi/perps-sdk, @lifi/perps-types and the provider packages. @lifi/perps-sdk 27.0.0 depends on @lifi/perps-types 24.0.0. Mixed majors read a different result shape.
• Update the backend and widget consumer pins in the same release. Do not deploy the new backend beneath a consumer that still reads success: the new ActionResult has no such field.
• This release changes the ActionResult response of /v1/perps/executeAction in place and adds no new API version. If an existing external consumer must keep the old shape, the API needs an explicitly versioned boundary, and this release does not provide one.

​

Action Types

All action types from the provider’s setup and actions arrays can be used with createAction/executeAction. The relay of the action descriptor says where each signed step goes: API steps go to executeAction, and CLIENT steps go from the client to the venue. See Providers.

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
revokeSessionAgent	Revoke	Remove the session agent the SDK signs with (Hyperliquid). The revoke action of approveAgent. Takes agentAddress.
revokeBuilderFee	Revoke	Revoke the builder fee approval (Hyperliquid). The revoke action of approveBuilderFee. No params.
revokeIntegrator	Revoke	Revoke the integrator approval (Lighter). The revoke action of approveIntegrator. No params.
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	Setup (choice)	Switch account operating mode (Hyperliquid: disabled, unifiedAccount, portfolioMargin; Lighter: simpleTradingAccount, unifiedTradingAccount). The values are bound in the options of the setup step.
accountType	Setup (choice)	Switch the Lighter account tier (plus or premium). The values are bound in the options of the setup step.
registerApiKey	Setup	Register a venue API key: rotate a Lighter signing-key slot, or register the Ondo HMAC key through the provider session
approveReadOnlyToken	Setup	Create and store a Lighter read-only auth token. A client-only plugin step: the SDK runs it and the backend never sees it as a setup action
siweLogin	Setup	Sign in to a provider session with an ERC-4361 challenge. Completed client-side; never sent to executeAction
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
addWithdrawalAddress	Setup	Add the login address to the venue’s withdrawal address book through the provider session (Ondo). Run it with perps.execute; see Withdrawal.
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, getTermsAcceptance } from '@lifi/perps-sdk';

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

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

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

// Reserve a shareable referral code for this address
await perps.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 request fails; a wallet signature refusal propagates as the wallet’s own error. A refused or uncertain step is a result in the report, not an exception. Read status on each result.

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