Unified Balance Kit: One Integration for Unified USDC Flows

Supporting USDC across multiple chains often means managing separate balances, chain-specific payout flows, fee estimation, and routing logic.

This complexity adds engineering overhead and makes multichain experiences harder to ship and maintain than they should be.

Today, we’re introducing Unified Balance Kit, a TypeScript SDK within App Kits that provides a streamlined interface for interacting with the unified balance model powered by Circle Gateway. 

Circle Gateway is the protocol that enables a unified USDC balance across supported blockchains and handles the underlying cross-chain movement of funds. Unified Balance Kit gives developers a simple, consistent way to integrate with that system, without needing to build custom multichain orchestration.

Instead of stitching together chain-specific contracts, ABIs, and routing logic, developers can use a single SDK to fund, view, estimate, and spend from a unified USDC balance across Circle Gateway–supported chains.

What developers can do with Unified Balance Kit

Fund a unified balance with deposit

deposit funds from the caller into the Gateway Wallet contract and credits the resulting unified balance to the caller .

const depositResult = await kit.deposit({
  from: {
    adapter: evmAdapter,
    chain: "Arc_Testnet",
  },
  amount: "100.00",
  token: "USDC",
});

Fund on behalf of another account with depositFor

depositFor funds from the caller into the Gateway Wallet contract and credits the unified balance to a specified recipient address instead of the caller.

const depositForResult = await kit.depositFor({
  from: {
    adapter: evmAdapter,
    chain: "Arc_Testnet",
  },
  amount: "100.00",
  token: "USDC",
  depositAccount: "0xRecipientUnifiedBalanceAccount",
});

Preview fees before execution with estimateSpend

estimateSpend simulates a spend using Gateway’s offchain system and SDK logic to preview fees (such as gas and protocol fees).

const estimate = await kit.estimateSpend({
  amount: "1.00",
  from: {
    adapter: evmAdapter,
    allocations: { amount: "100.00", chain: "Arc_Testnet" },
  },
  to: {
    adapter: evmAdapter,
    chain: "Ethereum_Sepolia",
    recipientAddress: "0xRecipientAddress",
  },
  token: "USDC",
});

Send USDC across destinations with spend

spend orchestrates the Gateway transfer flow by creating a burn intent, retrieving an attestation from the Gateway system, and submitting it to the Gateway Minter contract to mint USDC on the destination chain.

const spendResult = await kit.spend({
  amount: "1.00",
  from: {
    adapter: evmAdapter,
    allocations: { amount: "100.00", chain: "Arc_Testnet" },
  },
  to: {
    adapter: evmAdapter,
    chain: "Ethereum_Sepolia",
    recipientAddress: "0xRecipientAddress",
  },
  token: "USDC",
});

‍

A key advantage of Unified Balance Kit is that developers do not need to build separate application flows for each destination type. The flow keeps the same overall structure, with most destination-specific changes localized to the to parameter.

Return confirmed and pending balances with getBalances

getBalances returns a chain-agnostic view of balances across supported chains, with optional pending balances for deposits that are still finalizing onchain.

const balances = await kit.getBalances({
  sources: { account: "0xYourWalletAddress" },
  networkType: "testnet",
  includePending: true,
});

‍

Together, these operations cover the core unified balance workflow: funding a balance, funding on behalf of another account, checking balances, previewing fees, and spending across supported chains.

Unified Balance Kit also includes support for common production needs such as delegate management for Smart Contract Account wallets and configurable fee policies for applications that want to layer on monetization.

Getting started

Unified Balance Kit gives developers a more direct path to unified USDC balance and multichain payout flows without taking on the full orchestration burden themselves. Under the hood, it uses the unified balance model enabled by Circle Gateway.

To get started, install the package with:

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

‍

Then follow the Unified Balance docs to set up the adapters that match your environment, review the supported flows, and build your first deposit, estimate, and spend workflow.