Action Pattern

The create → authorize → execute pattern used by mutating operations

Most mutating operations (orders, cancellations, setup, withdrawals) follow the same create → authorize → execute pattern. A client-only session action is the exception: the provider plugin executes it directly and there is no backend-bound signed step.

createAction returns an actions[] array. Each entry carries its action type and one authorization payload selected by the action’s signingMethod. The SDK and registered provider plugin own dispatch; consumers should not infer a credential type from the provider name.

1. Create

Call /createAction with the provider, account address, action type, and action-specific params. The backend can return any public ActionStep variant:

Variant	Payload	Authorization
Eip712ActionStep	typedData	EIP-712 signature
WasmBlobActionStep	wasmSignParams	Provider WASM signer
EvmTxActionStep	txParams	Wallet-submitted EVM transaction
HmacActionStep	request	SDK-side HMAC over the exact request bytes
SiweActionStep	siwe	ERC-4361 personal_sign challenge
SessionActionStep	session	Client-only provider-session request; no execute round trip

The step’s action identifies its schema. A single create call can return more than one step — for example, an order can stage an updateLeverage step before placeOrder.

2. Authorize

Who authorizes a step comes from ProviderAction.signers:

• USER — a user-owned authorization path. Most USER steps invoke the wallet (for example agent approval, EVM deposits, SIWE login, and Hyperliquid withdrawals); a provider session step can instead use the client-held session established by SIWE.
• SDK — the provider plugin uses the credential it owns for that account. The concrete credential can be a Hyperliquid agent, a Lighter native signing key, an HMAC key, or a provider session.

An action can list both when the protocol requires two contributions. executeProviderSetupAction() coordinates setup schemes end-to-end, and high-level trading methods authorize SDK-signed actions automatically.

3. Execute

Send signed EIP-712, WASM, EVM, HMAC, or SIWE steps to POST /executeAction. SignedActionStep is a discriminated union that retains the original payload and adds its signature, transaction hash, or HMAC material. Do not send a SessionActionStep; the provider plugin completes it directly.

// One EIP-712 signed variant:
{ action: 'placeOrder', typedData: { /* ... */ }, signature: '0x...' }

executeAction returns one ActionResult per submitted step. Success results can include orderId, twapId, txHash, and explorerLink; failures contain error and can include a structured errorCode.

Attached TP/SL wires remain part of the placeOrder step. placeTriggerOrder is used for standalone trigger orders.

A provider plugin may implement onExecuteResults(address, results). The SDK calls it before surfacing a failure so the plugin can react to structured codes, such as evicting a locally stored credential the venue no longer accepts.