Relay a transaction - Rhinestone

Relay EVM contract calls or supported Solana instructions on a single chain. Use Send a transaction instead when the transaction must source funds from another chain or deliver tokens to the target chain.

Define the calls

For EVM, this example transfers 0.1 USDC from the account on Base Sepolia. Both wallet types use the same calldata. Calls run in order and revert together if one fails.

import { encodeFunctionData, erc20Abi, parseUnits } from "viem";
import { baseSepolia } from "viem/chains";

const usdc = "0x036CbD53842c5426634e7929541eC2318f3dCF7e";
const recipient = "0xd8da6bf26964af9d7eed9e03e53415d37aa96045";
const amount = parseUnits("0.1", 6);

const calls = [
  {
    to: usdc,
    value: 0n,
    data: encodeFunctionData({
      abi: erc20Abi,
      functionName: "transfer",
      args: [recipient, amount],
    }),
  },
] as const;

Send the transaction

Embedded wallet
Custom signer
REST API

Use wallet from Accounts after the user signs in; sends always use the authenticated account.sendIntent() prepares the route, requests passkey approval, and submits the transaction. Set source.chain and destination.chain to the same chain to keep funding and execution on Base Sepolia:For the Solana memo, use a managed wallet with experimental_solana, ready on Devnet after fresh passkey sign-in. data is base64. This no-delivery example has no source or dummy token: full sponsorship is required, and refusal fails without a user-paid fallback. Retain the entire result before handling failure, including any intent ID and submission metadata.The wallet shows Rhinestone’s prepared-action review before passkey approval. See Clear signing for what the review shows.closeOn: "completed" waits for completion rather than an earlier execution milestone. waitForHash: true also requests the onchain transaction hash. If a request times out, keep any returned intentId and check it with wallet.getIntentStatus(intentId); do not blindly resubmit. Inspect status: a pending status is not a failed transaction, even when that status response has success: false.

Choose who pays

This example uses sponsorshipMode: "required": sponsorship must succeed or the request fails. Set it to "disabled" for a user-paid quote, with enough USDC on Base Sepolia to cover fees as well as the transfer.Solana instructions can instead pay fees from one explicit same-cluster source token with sponsorshipMode: "disabled". They accept no source.maxAmount or positive app fee; appFees: { feeBps: 0 } disables any configured fee. Sponsorship covers fees, not assets consumed by instructions: fund those beforehand, then submit execution separately. No cross-VM calls, cross-cluster instructions, mixed Solana batches, or Solana SmartSessions are supported.Instruction labels are unverified; review does not decode or simulate effects. Instructions may move existing wallet assets. See availability and recovery and authority limits.Embedded wallets do not expose ranked quotes or per-category sponsorship controls through sendIntent(). See Sponsor fees for funding modes and fallback behavior.

Try atomic calls

This sponsored testnet demo uses the embedded wallet provider’s wallet_sendCalls to relay two 0.1 mUSD transfers on Base Sepolia. Sign in, mint mock tokens if needed, then approve both calls together. Unlike a queue of intents, these calls execute in one transaction and revert together.A calls ID identifies the submission, not its outcome. wallet_getCallsStatus returns an EIP-5792 numeric status: 100 pending, 200 confirmed, or 400 failed or expired. Passkey intents return no receipts; the calls ID is the intent ID, so read the transaction hash with wallet.getIntentStatus(callsId).

Use account from the Custom signer quickstart with @rhinestone/sdk@3.0.0. There is no separate relayTransaction SDK method: select a fee token in source and use destination.chain for a same-chain intent.For EVM, reuse the constants and calls above. For Solana, use the selected preparation below. Prepare, sign, and submit form one flow; later preparation examples are alternatives.

Prepare a same-chain route

Use an account configured for the selected VM and a funded source balance.prepareTransaction returns ranked intent routes. Review the recommended route’s assets, fees, and expiry before requesting a signature. To select another route, pass its intentId to signTransaction; never combine a signature from one route with another route.

Sign and submit

import { isExecutionError } from "@rhinestone/sdk/errors";

const signed = await account.signTransaction(prepared, {
  intentId: quote.intentId,
});
const submitted = await account.submitTransaction(signed);

try {
  const result = await account.waitForExecution(submitted);
  console.log(result.status, result.operations);
} catch (error) {
  if (error instanceof Error && isExecutionError(error)) {
    console.error(error.message, error.traceId, error.context);
  }
  throw error;
}

submitTransaction returns after the orchestrator accepts the intent. That acceptance is not an onchain success. Keep the returned intent ID and call waitForExecution or query its status until it reaches a terminal outcome. Status queries can return PENDING; waitForExecution waits for a terminal result or throws.

Outcome	Meaning
`PENDING`	The intent was accepted and its same-chain operation is still processing.
`COMPLETED`	The intent completed. Inspect grouped operation items for recorded transaction references.
`FAILED`	Execution failed. Inspect failed items and the execution error context.

Operations are grouped as { chainId, items }. Onchain items carry optional transaction references and, when failed, failureReason; EVM hashes are item.transaction.txHash after checking transaction.vm === "evm"; Solana signatures are item.transaction.signature when transaction.vm === "svm". A reference alone is not proof of finality. Keep submitted.id for rhinestone.getIntentStatus(submitted.id).If submission returns an uncertain network result, query the existing intent before preparing another one to avoid duplicate execution. If the quote expires before submission, prepare and sign a new route.

Choose who pays

Both transfer examples above are user-paid, so the account also needs enough funds to cover the quoted fees. Set sponsored: true during preparation to request sponsorship. This EVM example sponsors call execution; the Solana delivery keeps its source and uses the same flag:

const prepared = await account.prepareTransaction({
  destination: { chain: baseSepolia, calls: [...calls] },
  sponsored: true,
});

This no-delivery request may omit source only when sponsorship covers applicable costs. The account still needs the USDC transferred by the calldata; sponsorship does not supply it. Delivery or user-paid execution requires a source. Only fee categories present in the selected route are charged. Sponsorship is decided while quoting; a rejected sponsored request does not silently become user-paid. Follow Sponsor fees for selective categories, quote inspection, and fallback behavior.

Restrict the fee asset

The following fee-asset example is EVM-only.source.token selects one fee balance. Omitting source.chain uses the destination chain, so this selects USDC on Base Sepolia:

const prepared = await account.prepareTransaction({
  source: { token: usdc },
  destination: { chain: baseSepolia, calls: [...calls] },
});

Use the native token’s zero address to select the native balance instead. Insufficient selected funds do not trigger a search for another token or chain.

Run a Solana instruction batch

For native SOL transfers or same-chain actions, use destination.instructions, not delivery fields or EVM calldata. This concrete batch sends 0.001 SOL to each of two wallets from the managed wallet. Install @solana/web3.js; supply firstRecipientAddress and secondRecipientAddress as base58 wallet addresses.

import { PublicKey, SystemProgram } from "@solana/web3.js";
import { solanaDevnet } from "@rhinestone/sdk/solana";

const wallet = new PublicKey(account.getAddress("solana"));
const instructions = [firstRecipientAddress, secondRecipientAddress].map(
  (address) => SystemProgram.transfer({
    fromPubkey: wallet,
    toPubkey: new PublicKey(address),
    lamports: 1_000_000n,
  }),
);
const prepared = await account.prepareTransaction({
  destination: { chain: solanaDevnet, instructions },
  sponsored: true,
});
const quote = prepared.quotes.best;

Use the shared sign and submit flow above. Instructions run in order as one batch; supply 1–32 instructions and at most 8 address lookup tables. The managed wallet is the signer: do not require unrelated signers. Sponsorship pays execution costs, not the 0.002 SOL transferred or arbitrary account rent. Keep enough spendable SOL above the wallet’s rent reserve. For user-paid instruction execution, select a fee mint or the native SOL sentinel in source; see Sponsor fees. Do not combine instructions with destination token, amount, recipient, calls, or gas limit.

Set the destination gas limit

This option is EVM-only.destination.gasLimit sets the limit used to quote the calls. When omitted, the SDK leaves it to the orchestrator:

const prepared = await account.prepareTransaction({
  source: { token: usdc },
  destination: { chain: baseSepolia, calls: [...calls], gasLimit: 200_000n },
});

Estimate the calls and add headroom. A limit below actual usage makes execution run out of gas.

Extend the fill deadline

This option is EVM-only.Same-chain routes carry a two-minute onchain fill deadline. customDeadline overrides it with an absolute Unix timestamp in seconds, which is useful when a user reviews the action before approving:

const prepared = await account.prepareTransaction({
  source: { token: usdc },
  destination: { chain: baseSepolia, calls: [...calls] },
  customDeadline: Math.floor(Date.now() / 1000) + 900,
});

The value must be between two minutes and 24 hours from now; anything outside that range is rejected while quoting. The quoted expiresAt tracks it. This option is same-chain only — crosschain routes cannot set it.

Declare incoming funds

This option is EVM-only.source.auxiliaryFunds lets the route count a balance that has not landed yet but arrives before settlement. It works the same way here as for multichain transactions; see Quote against incoming funds.

Other account types

This section covers EVM accounts.The same prepare, sign, and submit contract supports plain EOAs, EIP-7702 accounts, and the SDK’s Nexus, Safe, Kernel, Startale, and HCA smart account providers. This guide uses the default Nexus account from the quickstart. A pre-signed native Safe transaction uses the separate Safe relay flow: see Relay a Safe transaction.For an EIP-7702 account in the SDK, include its initialization signature while preparing. Normal signTransaction collects delegation authorizations in the ordered proofs; do not pass separate authorizations to submission. Follow the EIP-7702 transaction flow.

Recovery guardians cannot sign an intent. Use account owners or a compatible session key for this flow; guardians authorize recovery UserOperations only.

For a call-only Caucasus relay, use destination.execution.calls and omit the delivery token and amount. Select one source chain/token to pay fees. Omit source only for no-delivery execution with effective sponsorship covering applicable orchestrator costs; denial cannot fall back to another balance, and sponsorship does not fund arbitrary caller-authored EVM call value. See execution and source-free limits.HTTP EIP-7702 authorizations answer returned signing requests in order with { kind: "eip7702", nonce, signature: { r, s, yParity } } in proofs[], not separate sponsor/recipient authorization bags. Use each request’s concrete chain and delegate; a configured delegation default is not an any-chain proof. Follow ordered signing and submission.

​Define the calls

​Send the transaction

​Choose who pays

​Try atomic calls

​Prepare a same-chain route

​Sign and submit

​Choose who pays

​Restrict the fee asset

​Run a Solana instruction batch

​Set the destination gas limit

​Extend the fill deadline

​Declare incoming funds

​Other account types

Define the calls

Send the transaction

Choose who pays

Try atomic calls

Prepare a same-chain route

Sign and submit

Choose who pays

Restrict the fee asset

Run a Solana instruction batch

Set the destination gas limit

Extend the fill deadline

Declare incoming funds

Other account types