gaslessWalletExecute

Run any contract call from the deterministic gasless wallet, with no native gas — an atomic batch of arbitrary { target, value, data } calls relayed by GaslessQ.

import { gaslessWalletExecute } from "@symmio/trading-core";
import { erc20Abi } from "viem";
 
// Approve a router, then call it — one atomic, gas-free batch.
const receipt = await gaslessWalletExecute(config, {
  calls: [
    { target: usdcAddress, abi: erc20Abi, functionName: "approve", args: [router, amount] },
    { target: router, data: routeCalldata },
  ],
  operationType: "bridgeWithdraw",
});

The SDK reads getGaslessWalletAddress(owner, walletId) and walletOperationNonces(owner, walletId, signerAccount) from the GaslessLayer, encodes execute((address,uint256,bytes)[]), signs, and submits through the same relay-instant endpoint with walletIds: ["<walletId>"].

walletId selects everything at once — the signed target, the nonce stream and the relayed id — so a positive id must match the wallet the operation was signed against. Changing the id to pick a different wallet needs a new target and a new signature; the SDK derives all three from the same walletId, so that only goes wrong if you sign by hand.

For the end-to-end story — funding the wallet, paying the fee, building a batch — see the Run any contract call gaslessly guide.

Two ways to give a call

Every entry in calls is either raw calldata or an ABI-level call the SDK encodes. Both forms mix freely in one batch, and value defaults to 0n.

calls: [
  // ABI form — encoded by the SDK with viem's `encodeFunctionData`.
  { target: usdcAddress, abi: erc20Abi, functionName: "approve", args: [router, amount] },
 
  // Raw form — for calldata you already have (a bridge quote, a router route).
  { target: router, data: routeCalldata },
];

The ABI form types args as readonly unknown[], so arguments are validated when they are encoded rather than by the compiler — a wrong arity or type throws before any signature prompt or network call. When you want compile-time-checked arguments, encode with viem yourself and pass the result as a raw call:

import { encodeFunctionData, erc20Abi } from "viem";
 
// `args` is fully inferred here.
const data = encodeFunctionData({ abi: erc20Abi, functionName: "approve", args: [router, amount] });
calls: [{ target: usdcAddress, data }];

Who pays

The wallet balance never pays the fee. The GaslessLayer prices the operation from the inner call selectors — not from the execute wrapper and not from operationType — and charges it to the account it resolves as the billing parent, bounded by that account’s diamond-side operational-fee allowance. A per-account daily free quota (resetting at 00:00 UTC) can waive it. Collateral parked at the wallet is a thing you can move, not a source of gas.

The payer is signerAccount (a virtual account rolls up to its parent sub-account), and the fee is taken through chargeOperationalFee on the core diamond.

Signing with a session key

A signer that is not the wallet’s owner is a delegate. The GaslessLayer then requires active InstantLayer delegations for the wallet-execution sentinel and every inner call selector — build the set with getGaslessWalletExecuteSelectors.

The delegation has to live on a sub-account: grantDelegation is onlyAccountOwner, and the AccountLayer reports no owner for a bare EOA, so an EOA delegator can never be authorized. Pass that sub-account as signerAccount — the wallet it resolves to is unchanged, because the gateway derives the wallet from ownerOf(signerAccount), which is the same owner and therefore the same address.

const calls = [{ target: usdcAddress, abi: erc20Abi, functionName: "transfer", args: [to, amount] }];
 
// Once, owner-signed (itself relayable, so it costs no gas either).
await grantDelegation(config, {
  account: { addr: subAccount, isPartyB: false },
  delegatedSigner: sessionKey,
  selectors: getGaslessWalletExecuteSelectors(calls),
  expiryTimestamp,
});
 
// Then, unattended — no wallet prompt.
await gaslessWalletExecute(config, { calls, signerAccount: subAccount, from: sessionKey });

The SDK probes those delegations before the signature prompt and throws GASLESS_SIGNER_NOT_DELEGATED naming the missing selectors, rather than letting the relayer fail with an opaque WalletDelegationMissing. Disable that probe with execution.preflightDelegation: false. The owner-signed path short-circuits with no extra reads.

Note the nonce moves with the account: walletOperationNonces is keyed on signerAccount, so a sub-account has its own counter, separate from the owner’s.

What the wallet can and cannot do

• Inner targets and selectors are unrestricted. Neither the SDK nor the relayer keeps an allow-list for wallet calls; authority comes from the signature. (This is unlike the transparent gasless mode, which relays a fixed selector set.) A delegated signer is the exception — it is confined to the selectors it was granted.
• The operation target must be the owner’s own wallet. Anything else reverts with InvalidWalletOperationTarget.
• The batch is atomic. If any call reverts, the whole operation reverts and the fee charge rolls back with it — a failed batch costs nothing but time.
• value is 0n in practice. The wallet holds no native token unless someone funded it directly, so a non-zero value reverts the batch.
• Custody is bound by construction. The address is a pure CREATE2 view of owner, so collateral at it can only ever be moved by that owner.

A deliberately different signature scheme

Wallet operations do not reuse the ordinary operation signing:

• the EIP-712 domain is { name: "GaslessGateway", version: "1" } with the GaslessLayer as verifyingContract — while the operation’s target is the wallet. Swapping the two yields InvalidWalletOperationTarget from simulation. (The domain string deliberately kept the contract’s old name; do not “fix” it.)
• the signed SignedOperation struct has five fields — no flexFields, no maxUses. The relay body still carries flexFields: [] and maxUses: 1, appended after signing; signing the 7-field InstantLayer struct produces a digest the gateway rejects.
• the nonce is walletOperationNonces(owner, walletId, signerAccount) + 1 — a separate counter from InstantLayer nonces, and a separate stream per wallet id. Wallet 0 keeps its original per-signer-account counter; every positive id counts on its own wallet.
• signerAccount.addr defaults to the owner wallet itself rather than a sub-account, and the deadline is 10 minutes.

Parameters

Returns

Throws

• SymmError("config", "GASLESS_NOT_CONFIGURED") / ("config", "GASLESS_UNSUPPORTED_CONTRACTS_VERSION").
• SymmError("api", "GASLESS_WALLET_UNAVAILABLE") — the gateway returned the zero address for the owner’s wallet (an unwired deployment answers 0x0 instead of reverting).
• A viem AbiEncodingLengthMismatchError (or similar) when an ABI-level call’s args do not match functionName. Thrown while encoding, before anything is signed or sent.
• SymmError("validation", "GASLESS_SIGNER_NOT_DELEGATED") — a non-owner signer is missing a delegation for the sentinel or an inner selector.
• SymmError("validation", "GASLESS_WALLET_OWNER_MISMATCH") — an explicit owner does not own signerAccount.
• SymmError("validation", "GASLESS_WALLET_ID_INVALID") — a walletId outside 0 … 2^256 − 1, or a JavaScript number.
• SymmError("api", "GASLESS_NONCE_STREAM_BUSY") — an earlier relay on this (walletId, signerAccount) stream is still unaccounted for; see nonce streams.
• SymmApiError with code GASLESS_RELAY_SUBMIT_FAILED — HTTP failure; InvalidWalletOperationTarget in the decoded revert means the operation’s target was not the owner’s wallet.
• SymmApiError with code GASLESS_SUBMIT_UNCONFIRMED — the outcome could not be established. The signature is spent either way, so replay the submit with resubmitGaslessRequest; signing a new operation would risk executing the batch twice.