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. Client-only session and SIWE steps are the exception: the provider plugin completes them directly with the venue 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; completed client-side, no execute round trip
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 fulfils a step comes from ProviderAction.signer:

• USER — the user’s wallet or consent must act. 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 SDK fulfils the step with the credential the provider plugin owns for that account. The concrete credential can be a Hyperliquid agent, a Lighter native signing key, an HMAC key, or a provider session.

signer names one party. 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, or HMAC steps to POST /executeAction. session and SIWE steps are completed client-side by the provider plugin and never sent; /executeAction rejects siweLogin. SignedActionStep is a discriminated union that retains the original payload and adds its signature, transaction hash, or HMAC material.

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

executeAction returns 202 with one ActionResult per attempted step. Each result carries a status: submitted, accepted, indeterminate or failed. A submitted or accepted result can include orderId, twapId, txHash, and explorerLink. A failed or indeterminate result contains error and can include a structured errorCode.

The HTTP status, the action status and the error cause are separate. 202 does not mean that the venue accepted a step. Execution stops at the first step that is failed or indeterminate, and the steps after it have no result. An indeterminate result means that you must read the account state before you submit the action again. See Execution reports and POST /executeAction.

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.