Make a swap - Rhinestone

Request the output token and amount on the target chain. Select one source chain and token. The wallet clients below quote the swap and any bridge, and deliver the requested output in one intent.

Choose the intent shape

Outcome	Destination delivery	Calls
Plain swap	Requested output token and amount	None
ERC-20 payment	Token needed on the target chain	Real `ERC20.transfer` calldata
Contract action funded by a trade	Tokens consumed by the contract	Real approval and application calls

For a plain swap with the SDK, omit destination.calls. Direct Caucasus HTTP selects one source chain/token and one destination asset, and omits destination execution for a token-only quote. Do not add dummy calldata, a self-transfer, or { data: "0x" }. Use target-chain token addresses for the requested token. For EVM funding, select one source token and chain from the user’s portfolio. Custom signer SDK portfolio reads are EVM-only; the embedded wallet can also read managed Solana holdings. Neither client searches or combines other balances; delivery requires a source even when sponsored.

Request a token-only swap

This example requests 100 USDC on Arbitrum and restricts funding to WETH on Base:

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

const wethOnBase = "0x4200000000000000000000000000000000000006";
const usdcOnBase = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
const usdcOnArbitrum = "0xaf88d065e77c8cC2239327C5EDb3A432268e5831";
const amount = parseUnits("100", 6);

For a self-send without destination execution, the amount can be treated as the target’s final balance when existing destination funds are also eligible as funding. In Caucasus HTTP, they must belong to the selected source pair. Both examples restrict the source to Base, so any USDC already on Arbitrum is outside that scope and the full 100 USDC is delivered.

Embedded wallet
Custom signer
REST API

Use the initialized wallet client from Accounts after the user signs in; sends always use the authenticated account:

const result = await wallet.sendIntent({
  source: { chain: base.id, token: wethOnBase },
  destination: { chain: arbitrum.id, token: usdcOnArbitrum, amount },
});

console.log(result);

This embedded-wallet swap uses numeric EVM chain IDs, one source token, and one destination token, with no calls for a plain swap. source.chain applies the WETH address to Base; omitting it funds from the destination chain rather than searching other chains. sendIntent() manages quote preparation and does not expose the custom signer SDK’s ranked prepared.quotes object.Sponsorship is required by default. Reuse the funding, review, and completion options from Send a transaction. Preserve the whole result, including intentId, submission flags, native destination identifier, and refund evidence; never blindly retry an uncertain submission.

Managed Solana boundary

Managed Solana same-cluster delivery requires matching SPL mints, so it is not a different-mint swap. Native SOL token delivery and cross-cluster transfers are unsupported. For an EVM → Solana token-delivery example, see Send a transaction; supply a destination mint and recipient, without calls or instructions. Do not rely on Solana → EVM delivery as a swap route yet; see Networks for current limitations. Solana SmartSessions and cross-VM contract execution are unsupported.

Omit destination.amount to request the maximum output from the source token. source.maxAmount caps the observed source balance, not the total spend. Neither client’s cap guarantees exact-input spend.

Use account from the Custom signer quickstart with @rhinestone/sdk@3.0.0 and the constants above. The later preparation examples are alternatives to this request:See Send a transaction for other delivery directions and recipient configuration.Review and authorize either preparation with the same SDK flow:

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

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

console.log(result.status, result.operations);

In the EVM example, the SDK uses viem chain objects. source selects WETH on Base; omitting source.chain uses the destination chain, not another portfolio balance.Review the selected quote’s input, output, fees, and expiry before signing. The requested output is not reduced by fees; the quote includes fees in its input cost. This example is user-paid. Set sponsored: true during preparation if your application pays the fees.If no route is available, check the balance, selected source, output amount, supported tokens, and liquidity. Prepare and sign a new route after expiry or a price-related execution failure. If submission has an uncertain result, query the submitted intent before creating another one.

Cap the selected source balance

The Solana debit-cap behavior is shown above. For an EVM source, set source.maxAmount to cap the observed WETH balance and omit destination.amount for max-output routing:

const prepared = await account.prepareTransaction({
  source: { chain: base, token: wethOnBase, maxAmount: parseUnits("0.05", 18) },
  destination: { chain: arbitrum, token: usdcOnArbitrum },
});

This is not a binding exact-input swap: the cap does not guarantee a particular spend or that the entire cap is consumed. Declared auxiliary funds and source-call provides are added after capping the observed balance. Read the selected quote to show actual input, output, and fees before signing.

Pin the swap venue

This option is EVM-origin only.The orchestrator sources swap routes from every venue the chain supports. quoters restricts that set:

const prepared = await account.prepareTransaction({
  source: { chain: base, token: wethOnBase },
  destination: { chain: arbitrum, token: usdcOnArbitrum, amount },
  quoters: { include: ["1inch", "0x"] },
});

Supported venues are 1inch, 0x, velora, kyberswap, fynd, fynd-hosted, bebop, and relay. { exclude: [...] } inverts the filter against the full set, and an empty allow-list fails the request rather than falling back to an unconstrained route.A venue-scoped session derives this pin on its own; see Swap sessions for how the two interact.

Deliver the output elsewhere

A plain swap credits the account itself. Set destination.recipient to deliver the output to another address instead:

const prepared = await account.prepareTransaction({
  source: { chain: base, token: wethOnBase },
  destination: {
    chain: arbitrum,
    token: usdcOnArbitrum,
    amount,
    recipient: "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
  },
});

Pass a managed EvmAccountConfig from @rhinestone/sdk/evm instead of an address to deliver into another smart account; do not pass the composite config. An explicit recipient is delivery-only and cannot coexist with destination calls. For a trade that funds calls, leave it unset and encode the receiving address in calldata, as shareRecipient does below.For EVM routes, settlement layer filters, ranked-quote selection, declared incoming balances, and destination gas limits work the same way here — see Send a transaction.

Estimate a swap

Run this request server-side; never expose the API key to a browser. This exact-in example estimates spending 0.05 WETH on Base for USDC on Arbitrum:

const apiKey = process.env.RHINESTONE_API_KEY;
if (!apiKey) throw new Error("Missing server-side API key");

const estimateBody = {
  account: { evm: { type: "erc7579" } },
  source: {
    vm: "evm",
    chainId: "eip155:8453",
    token: "0x4200000000000000000000000000000000000006",
    amount: "50000000000000000",
    assumptions: { deployed: true },
  },
  destination: {
    vm: "evm",
    chainId: "eip155:42161",
    token: "0xaf88d065e77c8cc2239327c5edb3a432268e5831",
  },
};

const response = await fetch(
  "https://v1.orchestrator.rhinestone.dev/quotes/estimate",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": apiKey,
      "x-api-version": "2026-09.caucasus",
    },
    body: JSON.stringify(estimateBody),
  },
);
if (!response.ok) throw new Error(`Estimate failed: ${response.status}`);

const estimate = await response.json();
const route = estimate.routes[0];
if (!route) {
  console.log("No estimate available", estimate.unavailableReason);
} else if (route.status === "over_capacity") {
  console.log("Indicative route exceeds current capacity", route.accuracy);
} else if (route.status === "ok") {
  console.log(route.cost.input, route.cost.output, route.cost.fees);
  console.log(route.accuracy, route.assumptions);
} else {
  throw new Error("Unsupported estimate status");
}

For exact-out, remove source.amount and set destination.amount to a base-unit decimal string, such as "100000000" for 100 USDC. Send exactly one amount side, not both or neither; do not send direction, amountIn, or amountOut.The account descriptor is hypothetical: supply types, not wallet addresses or signing configuration. source.assumptions.deployed affects only an ERC-7579 source; omission assumes undeployed, and EOA/Swig estimates ignore it. Returned assumptions describe what was priced; accuracy is exact or approximated, not a guarantee of execution.Estimates do not use actual destination-balance credit or accept caps, auxiliary funds, recipients, or execution. Even an ok estimate is not an executable quote: it has no intent ID or signing requests. Binding quotes use source.maxAmount as an observed-balance cap, not exact input. Follow the HTTP lifecycle before signing or submitting; see estimate migration for the contract.

Trade and deposit

This procedure is EVM-only. When the output feeds another action, include the actual calls and the matching destination token and amount in one intent. This example swaps WETH into 100 USDC on Base, approves the Steakhouse Prime USDC ERC-4626 vault, and deposits for shareRecipient:

const vault = "0xbeef0e0834849aCC03f0089F01f4F1Eeb06873C9";
const shareRecipient = "0xd8da6bf26964af9d7eed9e03e53415d37aa96045";

const vaultAbi = [
  {
    type: "function",
    name: "deposit",
    stateMutability: "nonpayable",
    inputs: [
      { name: "assets", type: "uint256" },
      { name: "receiver", type: "address" },
    ],
    outputs: [{ name: "shares", type: "uint256" }],
  },
] as const;

const fundedCalls = [
  {
    to: usdcOnBase,
    value: 0n,
    data: encodeFunctionData({
      abi: erc20Abi,
      functionName: "approve",
      args: [vault, amount],
    }),
  },
  {
    to: vault,
    value: 0n,
    data: encodeFunctionData({
      abi: vaultAbi,
      functionName: "deposit",
      args: [amount, shareRecipient],
    }),
  },
] as const;

Embedded wallet
Custom signer

Submit the shared calls with the embedded wallet’s field names:

const result = await wallet.sendIntent({
  source: { chain: base.id, token: wethOnBase },
  destination: {
    chain: base.id,
    token: usdcOnBase,
    amount,
    calls: [...fundedCalls],
  },
});

Submit the same calls with the custom signer SDK’s field names:

const prepared = await account.prepareTransaction({
  source: { chain: base, token: wethOnBase },
  destination: { chain: base, token: usdcOnBase, amount, calls: [...fundedCalls] },
});

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

The output delivery and calls belong to one intent. The approval and deposit execute in order and revert together if either call fails. This is not a queue of separate trades. See Sponsor fees for funding modes. Continue to the end-to-end transaction flow for status and recovery details.

​Choose the intent shape

​Request a token-only swap

​Managed Solana boundary

​Cap the selected source balance

​Pin the swap venue

​Deliver the output elsewhere

​Estimate a swap

​Trade and deposit

Choose the intent shape

Request a token-only swap

Managed Solana boundary

Cap the selected source balance

Pin the swap venue

Deliver the output elsewhere

Estimate a swap

Trade and deposit