Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

SDK

execute

Submit one or more calls from a wallet. client.execute accepts either an admin pair (wallet + signer) or a session, plus the calls to run.

Keystore impact

ScenarioTouches Keystore?
First admin execute on a fresh walletYes (admin key registered)
Subsequent admin execute callsNo
Any session executeNo (session was registered at grant time)

Admin path

The wallet's admin signs the intent. Use this for first-party operations.

import { createClient, BNB, signerFromPrivateKey } from "@altananetwork/sdk";
 
const client = createClient({ chains: [BNB] });
const signer = signerFromPrivateKey("0x...");
const wallet = await client.createWallet({ signer });
 
const result = await client.execute({
  wallet,
  signer,
  calls: { to: "0xRecipient...", value: 1_000_000_000_000_000n }, // 0.001 BNB on BNB Smart Chain
});
 
console.log(result.status, result.transactionHash);

Session path

A session signs the intent. Use this for agent-driven operations.

// `client` and `session` from grantSession
const result = await client.execute({
  session,
  calls: [{ to: "0xUniswapRouter...", data: "0x...", value: 0n }],
});

Parameters

client.execute(opts: ClientExecuteOptions): Promise<ExecuteResult>;
 
type ClientExecuteOptions =
  | {
      wallet: Wallet;
      signer: Signer;
      calls: Call | readonly Call[];
      feeToken?: Address | readonly Address[];  // one token to force, or a list to choose from
      noWait?: boolean;                         // return as soon as submitted, don't wait for confirmation
      chainId?: number;                         // defaults to the client's default chain
    }
  | {
      session: Session;
      calls: Call | readonly Call[];
      feeToken?: Address | readonly Address[];
      noWait?: boolean;
      chainId?: number;
    };
 
type Call = {
  to: Address;
  data?: Hex;
  value?: bigint;
};

Returns

type ExecuteResult = {
  callsId: Hex;
  status: "CONFIRMED" | "FAILED" | "PENDING";
  transactionHash?: Hex;
  statusCode?: number;   // the relay's raw numeric status, when observed
  feeToken?: Address;    // the token the relay charged its fee in (zero address = native)
};

A failed execute returns status: "FAILED"; it does not throw. Check the status rather than relying on try/catch. statusCode says which kind of failure: 300โ€“499 is the relay rejecting the bundle before inclusion (nothing reached the chain), 500+ an on-chain failure. See Errors for the full code table and how to tell the failure classes apart.

Quoting first

client.quoteExecute takes the same options as execute and returns the relay's quote for those exact calls without signing or sending anything: the maximum fee and the feeToken it is charged in (the zero address is native), the native value the calls carry, and feeTokenDeficit, what the wallet is short by if anything. Use it to size a send that must leave room for the fee, instead of guessing a reserve:

const calls = [{ to, value: balance, data: "0x" }];
const q = await client.quoteExecute({ wallet, signer: wallet.signer, chainId, calls });
const value = q.feeToken === NATIVE_TOKEN ? balance - q.fee : balance;
await client.execute({ wallet, signer: wallet.signer, chainId, calls: [{ to, value, data: "0x" }] });

Notes

  • First execute on a fresh wallet auto-registers the admin key in Keystore. initialRegisterKey is prepended transparently in the same userOp.

  • Empty calls is rejected. client.execute({ wallet, signer, calls: [] }) errors. Pass at least one call.

  • Session execute must match the grant. The session's permissions + expiry + publicKey values must equal what was committed at grant. Don't JSON.stringify a Session (it throws on bigint limits and embeds the session key) โ€” persist with serializeSession and restore with deserializeSession.

  • chainId selects the chain. Omit it to use the client's default chain; pass one of the client's configured chains to target another.

  • With noWait: true, you get status: "PENDING" and a callsId to poll later.

  • The relay fee is paid in a token the wallet holds. Every chain's relay accepts its native token (BNB, ETH, CELO), and some accept more: on Celo the relay also takes USDC and USDT, priced live, so a wallet holding either transacts without CELO. client.feeCurrencies() lists what a chain's relay accepts, with the rate for each; the token charged comes back as feeToken on the result. Which token is used:

    • feeToken is one address: that token, for any key.
    • feeToken is a list: the first token of the list that the relay accepts on the chain and the wallet holds. If none qualifies the call fails before anything is sent, naming the accepted tokens and what the wallet holds. An empty list names nothing.
    • Nothing set, wallet key: the request names no token and the relay charges whichever accepted token the wallet holds (the most valuable one when it holds several).
    • Nothing set, session key: the SDK picks among the tokens of the session's spend caps (native counts when the cap is native), keeps those the relay accepts, and names the one the wallet holds the most of. A session whose wallet holds none of its capped tokens fails before anything is sent. A session pays fees only from its caps, so a session meant to run on a stablecoin needs a cap on it: see grantSession.

    $U is for ERC-8183 job escrow and x402 payments, not relay fees. An unaccepted feeToken is rejected before the call runs, and the error names the tokens the relay does accept.

  • Native payouts via .transfer()/.send() cannot reach the wallet. Those Solidity primitives forward a 2300-gas stipend, which is not enough to run the wallet's delegated (EIP-7702) account code โ€” the paying contract reverts. Contracts that pay with a full-gas call{value:} work fine, as do all ERC-20 transfers. See the failure-class table in Errors for the known cases and workarounds.