Skip to main content
The App Kit SDK includes the Unified Balance capability that combines USDC from multiple blockchains into a single, instantly spendable balance. It is built on top of Circle Gateway and handles the Gateway workflow for deposits and spends across EVM and non-EVM blockchains.

​
How it works

Unified Balance works by depositing funds held across multiple blockchains into a single, chain-agnostic Unified Balance. Those funds are then available to spend instantly on any blockchain. The process is illustrated below:

​
What to know about wallet models

  • Some wallet models cannot sign their own Unified Balance spends, including Circle Wallets SCAs and Privy server wallets. Use the delegate workflow: the wallet remains the depositor, and an authorized EOA signs each spend.
  • Circle Wallets are chain-specific. For Unified Balance flows that draw from multiple source blockchains, use the wallet address for each source blockchain.
  • For Unified Balance spends, create one source per wallet and chain as needed. The Circle Wallets adapter is stateless, so you can reuse the same adapter configuration and pass the wallet address in each operation context.
  • Circle Wallets smart contract account (SCA) deposits require allowanceStrategy: "approve". USDC permit signatures use ecrecover, which does not accept the SCA’s ERC-1271 signature, so the SDK uses an onchain approve.
Unified Balance is built on Circle Gateway. For production considerations related to deposits, spends, and fund removal, see the Gateway implementation checklist.

​
Quick look

This code snippet creates a Unified Balance by depositing funds from two blockchains to spend on a third:
TypeScript
// Deposit 1.00 USDC into the Unified Balance from Base
const depositBase = await kit.unifiedBalance.deposit({
  from: { adapter: viemAdapter, chain: "Base_Sepolia" },
  amount: "1.00",
  token: "USDC",
});
// Deposit 1.00 USDC into the Unified Balance from Arbitrum
const depositArb = await kit.unifiedBalance.deposit({
  from: { adapter: viemAdapter, chain: "Arbitrum_Sepolia" },
  amount: "1.00",
  token: "USDC",
});
// Spend 1.50 USDC from the Unified Balance on Arc
const spendResult = await kit.unifiedBalance.spend({
  amount: "1.50",
  from: { adapter: viemAdapter },
  to: {
    adapter: viemAdapter,
    chain: "Arc_Testnet",
    recipientAddress: "0xRecipientAddress",
  },
});
For a complete end-to-end flow, follow the quickstart for your scenario:

​
Installation

Install the App Kit SDK to use Unified Balance. If you only need Unified Balance and don’t want to install the full App Kit SDK, follow the steps below to install the standalone Unified Balance Kit.
1

Install Unified Balance Kit

npm install @circle-fin/unified-balance-kit
2

Install adapters

Use the adapter setup guide to choose the right wallet model for your app, including browser wallets and Circle Wallets.
npm install @circle-fin/adapter-viem-v2 viem