End-to-end transaction flow

Every multichain transaction follows the same lifecycle, but each client exposes different boundaries. Embedded wallets manage preparation, authorization, and submission through sendIntent(). The custom signer SDK exposes each step. REST integrations call the endpoints directly.

Transaction lifecycle

Define the target chain, required tokens, destination calls, and source constraints.
Prepare a route and review its inputs, outputs, fees, and expiry.
Complete any token requirements for the account type.
Authorize the exact prepared route.
Submit the signed intent.
Track the intent until it completes or fails.

An accepted submission is not an onchain success. Keep the intent ID so you can resume status checks without creating another transaction.

Follow the flow

Reuse the chains, token addresses, amount, and calls from Send a transaction.

Embedded wallet
Custom signer
REST API

Use the initialized oneAuth client and authenticated accountAddress from Accounts.

Review, authorize, and submit

const result = await oneAuth.sendIntent({
  accountAddress,
  targetChain: arbitrum.id,
  sourceChainId: base.id,
  sourceAssets: [usdcOnBase],
  tokenRequests: [{ token: usdcOnArbitrum, amount }],
  calls: [...calls],
  closeOn: "completed",
  waitForHash: true,
});

Embedded wallets prepare the route, handle their smart-account token requirements, request passkey approval, and submit the intent. They do not expose the custom signer SDK’s ranked quotes or separate signing and submission methods.Sponsorship is required by default. closeOn: "completed" waits for completion; waitForHash: true separately requests the onchain transaction hash. Add clear signing when your application needs prepared-action review.Save any non-empty result.intentId before handling errors. STATUS_TIMEOUT, HASH_TIMEOUT, or a dialog cancellation with an intent ID can occur after submission. They are not reasons to send a replacement intent. If the submission outcome is uncertain and no ID was returned, reconcile intent history before starting another.

Check or resume execution

Use getIntentStatus() when you have an intent ID. Check for a lookup error before interpreting the status:

async function waitForWalletCompletion(intentId: string) {
  for (let attempt = 0; attempt < 60; attempt++) {
    const latest = await oneAuth.getIntentStatus(intentId);

    if (latest.error) {
      console.error(latest.error.code, latest.error.message);
    } else if (
      latest.status === "completed" ||
      latest.status === "failed" ||
      latest.status === "expired"
    ) {
      return latest;
    }

    await new Promise((resolve) => setTimeout(resolve, 2_000));
  }

  return undefined;
}

if (!result.intentId) {
  throw new Error(result.error?.message ?? "No intent ID returned");
}

const latest = await waitForWalletCompletion(result.intentId);

if (!latest) {
  console.log("Check this intent again later", result.intentId);
} else if (latest.status === "completed") {
  console.log(latest.intentId, latest.transactionHash);
} else {
  console.error("Intent failed", latest.intentId, latest.status);
}

The helper stops after 60 status requests. undefined means the outcome is still unknown, not failed; retain the ID for a later check. Stopping your poll does not cancel the intent.In @rhinestone/1auth@0.10.1, getIntentStatus() returns success: false for valid non-terminal statuses. It also returns a synthetic status: "failed" with STATUS_FAILED or NETWORK_ERROR when the lookup fails. An error-free failed or expired status, by contrast, is an execution outcome.

Recover from errors

Signal	Action
`STATUS_TIMEOUT` or `HASH_TIMEOUT`	Keep the intent ID and query status. A waiting timeout does not prove execution failure.
`STATUS_FAILED` or `NETWORK_ERROR` during a status lookup	Retry the status read, not the transaction. Check credentials if failures persist.
`USER_CANCELLED` or `USER_REJECTED`	Do not retry automatically. Query any existing intent ID before asking for another approval.
Error-free `failed` or `expired` status	Inspect the failure before asking the user to authorize another intent.

Local statuses such as submitted, claimed, preconfirmed, filled, and completed are not the custom signer SDK’s uppercase statuses. Record error.details?.traceId when present; do not show raw diagnostics or simulation URLs to users.

Use the account and backend SDK instance from the Custom signer quickstart.

Prepare and inspect

const prepared = await account.prepareTransaction({
  sourceChains: [base],
  sourceAssets: [usdcOnBase],
  targetChain: arbitrum,
  calls: [...calls],
  tokenRequests: [{ address: usdcOnArbitrum, amount }],
});

const quote = prepared.quotes.best;
console.log(quote.cost.input, quote.cost.output, quote.cost.fees);
console.log(quote.expiresAt, prepared.quotes.traceId);

prepared.quotes.best is the recommended route. To choose another, select it from prepared.quotes.all. Show the user what the selected route spends, delivers, and charges before signing. expiresAt is a Unix timestamp in seconds.Smart accounts handle approvals and wrapping in the route. A plain EOA must first complete the selected quote’s token requirements.

Sign the selected route

if (Date.now() >= quote.expiresAt * 1_000) {
  throw new Error("Quote expired; prepare and review a new route");
}

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

The account signs the required origin, destination, and target-execution data using its configured owners or session. Never combine a signature from one route with another route, or feed manually reconstructed REST sign data into this SDK flow.

Submit and wait

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

if (Date.now() >= quote.expiresAt * 1_000) {
  throw new Error("Quote expired; prepare and sign a new route");
}

const submitted = await account.submitTransaction(signed);
console.log(submitted.id, submitted.traceId);

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

submitTransaction returns a handle after acceptance. Save its id and traceId. waitForExecution polls until completion and throws when execution fails; it has no application deadline. To resume a status check, call rhinestone.getIntentStatus(submitted.id) with the SDK instance from the quickstart.

Interpret status and recover

Status	Meaning
`PENDING`	At least one operation is still processing. Status queries can return this; `waitForExecution` keeps polling.
`COMPLETED`	Every operation completed successfully. Completed operations include `txHash`.
`FAILED`	At least one operation failed. Inspect its `failureReason` and the execution error context.

Re-quote and collect fresh signatures after quote expiry. For REVERTED, fix the target calls or stale swap assumptions before requesting another signature. For BRIDGE_REFUNDED, inspect the error context for known refunds; a refund does not turn the intent into a success.If submission or polling returns an uncertain network result, query the existing intent before creating another. Keep the quote or submission traceId for support.

A direct integration uses POST /quotes, POST /intents, and GET /intents/{id}. This EOA example delivers 100 USDC from Base to the same EOA on Arbitrum, without destination calls. Unlike the other tabs, it does not forward the tokens to a payment recipient.Keep the API key on your backend. The signing example assumes walletClientFor(chainId) returns a viem wallet client for the same EOA on each requested chain.

Request and select a route

const baseUrl = "https://v1.orchestrator.rhinestone.dev";
const [eoaAddress] = await walletClientFor(base.id).getAddresses();
if (!eoaAddress) throw new Error("Connect an EOA first");

const apiKey = process.env.RHINESTONE_API_KEY;
if (!apiKey) throw new Error("RHINESTONE_API_KEY is required");

const headers = {
  "Content-Type": "application/json",
  "x-api-key": apiKey,
  "x-api-version": "2026-04.blanc",
};

const quoteResponse = await fetch(`${baseUrl}/quotes`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    account: { address: eoaAddress, accountType: "EOA" },
    destinationChainId: `eip155:${arbitrum.id}`,
    tokenRequests: [
      { tokenAddress: usdcOnArbitrum, amount: amount.toString() },
    ],
    accountAccessList: {
      chainTokens: {
        [`eip155:${base.id}`]: [usdcOnBase],
      },
    },
  }),
});

if (!quoteResponse.ok) throw new Error(await quoteResponse.text());
const { routes } = await quoteResponse.json();
const route = routes[0];
if (!route) throw new Error("No route available");

Inspect the selected route’s cost, expiresAt, and settlement layer before asking for authorization. See Create Quote for the complete request and response.

Complete token requirements

For an EOA, inspect the selected route’s tokenRequirements. For every requirement on its keyed source chain:

For approval, call approve(requirement.spender, requirement.amount) on the keyed ERC-20 token.
For wrap, deposit at least requirement.amount into that chain’s wrapped-native token contract.
Wait for each transaction receipt before continuing. Re-quote if the route expires while the user completes these transactions.

This is based on account type, not client choice. An EOA using REST or @rhinestone/sdk must complete the same operations. For the SDK’s recommended route, read prepared.quotes.best.tokenRequirements; the SDK does not execute them.For a smart account, set account.accountType to ERC7579 and include required setupOps for an undeployed account. Approvals and wrapping run as preclaim operations instead of EOA token requirements. Embedded wallets use this smart-account path.

Sign the selected route

Sign every origin payload in order and the destination payload when present:

import type { TypedDataDefinition } from "viem";

async function signEvmPayload(
  payload: TypedDataDefinition & { kind?: string },
) {
  if (payload.kind && payload.kind !== "eip712") {
    throw new Error(`Unsupported payload: ${payload.kind}`);
  }

  const { kind: _kind, ...typedData } = payload;
  const chainId = Number(typedData.domain?.chainId);
  if (!Number.isSafeInteger(chainId) || chainId <= 0) {
    throw new Error("Signing payload has no valid EVM chain ID");
  }

  return walletClientFor(chainId).signTypedData({
    ...typedData,
    account: eoaAddress,
  });
}

if (Date.now() >= route.expiresAt * 1_000) {
  throw new Error("Quote expired; request and review a new route");
}

const origin = await Promise.all(route.signData.origin.map(signEvmPayload));
const destination = route.signData.destination
  ? await signEvmPayload(route.signData.destination)
  : undefined;

These signatures authorize only this route. A raw smart-account integration must encode signatures for its ERC-1271 validator and sign targetExecution when present. Use the custom signer SDK or an embedded wallet unless your integration implements that account-specific encoding.

Submit the selected route

if (Date.now() >= route.expiresAt * 1_000) {
  throw new Error("Quote expired; request and sign a new route");
}

const submitResponse = await fetch(`${baseUrl}/intents`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    intentId: route.intentId,
    signatures: {
      origin,
      ...(destination ? { destination } : {}),
    },
  }),
});

if (!submitResponse.ok) throw new Error(await submitResponse.text());
const result = await submitResponse.json();

Keep route.intentId even if the submission response is lost. Query it before retrying so you do not create a duplicate intent. See Create Intent for the full submission contract.

Track execution

async function pollIntent(intentId: string) {
  for (let attempt = 0; attempt < 60; attempt++) {
    const response = await fetch(`${baseUrl}/intents/${intentId}`, { headers });
    if (!response.ok) throw new Error(await response.text());

    const latest = await response.json();
    if (latest.status === "COMPLETED" || latest.status === "FAILED") {
      return latest;
    }

    await new Promise((resolve) => setTimeout(resolve, 2_000));
  }

  return undefined;
}

const latest = await pollIntent(result.intentId);
console.log(result.intentId, latest);

PENDING is non-terminal. An exhausted poll or failed status request leaves the outcome unknown; keep the ID and query again later. On FAILED, inspect operations for the failed chain, operation, and failureReason. See Get Intent for the complete status response.

Send a transaction

Build token requests, calls, and source constraints.

Unified balance

Read spendable balances across supported chains.

​Transaction lifecycle

​Follow the flow

​Recover from errors

​Interpret status and recover