Unified balance - Rhinestone

A unified balance groups an account’s available assets across supported chains. It is a portfolio view, not a promise that one quote aggregates every balance. The SDK, embedded wallet, and direct HTTP flows select one funding chain/token pair before quoting.

Select funding from the portfolio

Display the balances, then let your application or user choose one source chain and token. The orchestrator quotes swaps, bridges, and fees for that selected balance; it does not search the portfolio or combine balances across tokens or chains. A delivery always requires a source. Omitting source.chain selects the destination chain, not the best available chain. Source-free execution has client-specific sponsorship requirements; see Sponsor fees. If a selected balance cannot fund the request, choose another source deliberately and review a new quote.

A portfolio is a balance snapshot, not a reservation guarantee. Prepare a transaction to receive the executable quote and current costs.

Spendable balance

Portfolio results reflect observed availability, not reserved funds. Concurrent intents and balance changes can invalidate a quote; keep pending intent IDs rather than treating the portfolio as double-spend protection. Refresh after completed or failed intents, deposits, withdrawals, and other balance changes.

Read and spend a unified balance

Embedded wallet
Custom signer
REST API

Use the initialized wallet client from Accounts. Read the authenticated EVM address from session.accounts.evm.address, including when requesting that user’s managed Solana holdings. See the migration guide for nested sessions and sends.Only effectively fully sponsored no-delivery execution with sponsorshipMode: "required" can omit source in the wallet SDK. Sponsorship does not supply assets consumed by calls or instructions.

Read assets

Use getAssets to read the portfolio. These alternatives depend only on your configured wallet:With experimental_solana, reads for the session’s own EVM address add managed Solana rows. Other addresses and EIP-1193 wallet_getAssets remain EVM-only. AssetBalance.chainId is number | SolanaChainId: narrow it before passing a row to EVM-only code. Solana mainnet rows belong to mainnets; Devnet rows belong to testnets. Failed Solana reads appear in unavailableChains without failing the whole portfolio request; an unavailable cluster is not a zero balance.Holdings do not prove wallet readiness, route availability, or pooled spending power. Setup does not fund a wallet. Confirm cluster readiness before funding.Each balance includes its chain ID, token address, symbol, decimals, and a base-unit balance string. getAssets requires the application access-token configuration from Sponsorship setup, including for user-paid intents. The access token identifies the application; it does not grant fee sponsorship by itself.getAssets rejects on missing app credentials, access-token failures, or portfolio request failures. Handle it with try/catch. This differs from sendIntent, which returns a structured success or failure result.

Fund an intent

Reuse the tokens, amount, and calls from Send a transaction. Choose one balance from the portfolio as the source:

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

source takes exactly one token address or SPL mint, not a token symbol. For managed Solana, use the same-cluster delivery example, selecting the row’s cluster and mint explicitly. Native SOL holdings do not imply native SOL token-delivery support. A source can prevent a route even when the portfolio has enough value elsewhere.Omitting source.chain funds from the destination chain. Do not treat that call shape as a request to search the full crosschain portfolio.Sponsorship is required by default. sendIntent() does not expose the custom signer SDK’s prepared quote object to your application. See Send a transaction for funding and review options, then use the result to track the intent.

Use account from the Custom signer quickstart.

Read assets

SDK portfolio reads are EVM-only. getPortfolio does not provide Solana balances, including on an account that manages both VMs. For Solana, read native SOL and SPL balances through a cluster RPC or your own indexer, then select the source explicitly using Solana transaction shapes. Preserve the native SOL rent reserve; an observed balance is not a guaranteed spendable amount. Do not infer route availability from an RPC balance.

const portfolio = await account.getPortfolio();

for (const token of portfolio) {
  console.log(token.symbol, token.chains);
}

Mainnet balances are returned by default. Pass true for testnet balances:

const testnetPortfolio = await account.getPortfolio(true);

SDK chain entries retain numeric chain IDs and bigint amount values. Apply each entry’s decimals before displaying amounts; this read schema differs from the CAIP-2 chains used in quote requirements and status groups.

Prepare funding

Reuse the tokens, amount, and calls from Send a transaction. After the user selects Base USDC from the portfolio, prepare that source explicitly:

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

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

The selected source can prevent a route even when the portfolio has enough value elsewhere. Changing it requires a new quote, not broader implicit funding. Review the selected quote’s inputs, outputs, and fees before signing; see Send a transaction for signing and submission.

Read assets

Call GET /accounts/{accountAddress}/portfolio with an EVM EOA or smart-account address. This endpoint and its filters are EVM-only, not a per-VM portfolio API. Run it on your backend; keep the API key out of browser code.

const baseUrl = "https://v1.orchestrator.rhinestone.dev";
const apiKey = process.env.RHINESTONE_API_KEY;
if (!apiKey) throw new Error("RHINESTONE_API_KEY is required");

const accountAddress = "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045";
const url = new URL(`${baseUrl}/accounts/${accountAddress}/portfolio`);
url.searchParams.set("filterEmpty", "true");

const response = await fetch(url, {
  headers: {
    "x-api-key": apiKey,
    "x-api-version": "2026-09.caucasus",
  },
});

if (!response.ok) throw new Error(await response.text());
const { portfolio } = await response.json();

for (const token of portfolio) {
  console.log(token.symbol, token.chains);
}

The response groups each token’s balances by chain. For example:

{
  "portfolio": [
    {
      "symbol": "USDC",
      "chains": [
        {
          "chainId": "eip155:8453",
          "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
          "decimals": 6,
          "amount": "500000"
        }
      ]
    }
  ]
}

amount is a base-unit string: this example represents 0.5 USDC on Base. Apply each chain entry’s decimals before displaying or combining amounts; the same token can have different decimals across chains. filterEmpty=true omits empty balances.

Filter by chain or token

Without filters, the endpoint reads across supported EVM chains. To limit the request, add repeated chainIds parameters before calling fetch:

url.searchParams.append("chainIds", "eip155:10");
url.searchParams.append("chainIds", "eip155:8453");

Alternatively, add repeated tokens parameters using eip155:<chainId>:<tokenAddress> values:

url.searchParams.append(
  "tokens",
  "eip155:10:0x0b2c639c533813f4aa9d7837caf62653d097ff85",
);
url.searchParams.append(
  "tokens",
  "eip155:8453:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
);

These filters scope the portfolio read, not quote funding. Select one source.chainId and source.token before a delivery or user-paid quote; omitting source does not search the portfolio. Follow the REST API tab in End-to-end transaction flow, or see singular quote selection.

Keep displayed and executable amounts distinct

Display portfolio balances as available assets, not guaranteed transaction outputs.
Use the prepared quote to show exact inputs, outputs, and fees when your client exposes one.
Keep pending intent IDs and refresh balances after their terminal result.
Do not add an existing balance to SDK source.auxiliaryFunds or HTTP source.auxiliaryFunds; that double-counts funds.
If funding is insufficient, change only the selected funding pair the user agrees to change, then request and review a new quote.

Next, send a multichain transaction or make a swap using the available balance.

​Select funding from the portfolio

​Spendable balance

​Read and spend a unified balance

​Read assets

​Fund an intent

​Read assets

​Prepare funding

​Read assets

​Filter by chain or token

​Keep displayed and executable amounts distinct

Select funding from the portfolio

Spendable balance

Read and spend a unified balance

Read assets

Fund an intent

Read assets

Prepare funding

Read assets

Filter by chain or token

Keep displayed and executable amounts distinct