From Gateway Primitives to Unified Balance Kit Methods

Circle Gateway introduces a permissionless workflow that addresses the issue of maintaining separate balances on each chain, freeing up working capital by consolidating USDC into a unified balance. Once deposits are finalised, that balance can be quickly accessed across all supported blockchains.

Unified Balance Kit provides an SDK surface built on top of Gateway and makes it easier for developers to integrate Gateway into their applications via methods instead of manually orchestrating Gateway primitives.

There are use cases that require protocol-level control or custom behaviors, which call for integration at the Gateway layer, however, common production unified balance flows can be simplified by using the Unified Balance Kit.

Migration considerations

If you already integrate with Gateway and are deciding whether to move to Unified Balance Kit or considering whether to integrate Gateway directly versus through the kit, this list of questions can help you think through the decision.

1. Is your flow basically deposit to a unified balance, then payout to addresses across different chains?
2. Do you assemble burn intents, request attestations and submit mint requests manually?
3. Do you call separate Gateway APIs for confirmed balance and pending deposits?
4. Before a spend is signed, do you surface fees to users or set maxFee yourself (especially on forwarding routes)?
5. Do you use Gateway Forwarding Service for payouts to recipient addresses?
6. Are you supporting smart contract account wallets as source depositors for Gateway balances?
7. Do you parse API responses to extract key information like txHash, fees, steps or transferId?

If most of your answers are yes, then it is worth considering migrating over to Unified Balance Kit.

Mapping Gateway steps to Unified Balance methods

Migration notes

Deposit. Deposits must use Gateway Wallet deposit methods. A standard ERC-20 transfer to the Gateway Wallet contract can permanently lose USDC. See Unified Balance Kit quickstarts for deposit() and depositFor() for usage examples.

Balance. getBalances({ includePending: true }) replaces separate POST /v1/balances and pending-deposit reads. Use the confirmed total as spendable balance, and show pending deposits in status or support context, instead of immediately spendable inventory.

Estimate. Call estimateSpend() only when your product previews fees or sets maxFee, especially on forwarding routes. Pass the same route shape you would use for spend(), including useForwarder and explicit source allocation when required.

Spend. A Gateway transfer runs through these steps:

1. Build a transfer specification.
2. Construct and sign a burn intent.
3. Submit the burn intent to Gateway (POST /v1/transfer).
4. Receive an attestation.
5. Call the Gateway Minter on the destination chain.

spend() runs that full sequence in one call. The returned SpendResult includes txHash, fee breakdown, ordered steps, and transferId when forwarding applies.

Forwarding. Set useForwarder: true on the destination—the kit maps this to POST /v1/transfer?enableForwarder=true. When the response includes a transferId, store it and poll GET /v1/transfer/{id} for forwarded transfer status. See How-to: Use Forwarding Service.

Delegates. Smart contract accounts, including Circle Wallets SCAs, cannot sign Gateway burn intents directly. For each chain, authorize an EOA delegate, confirm readiness with getDelegateStatus() before spending, then call spend() with the delegate adapter and the owner's sourceAccount. Treat delegates as high-privilege signers over the deposited balance on the chain where they are authorized.

If you only need the unified balance functionality, the standalone @circle-fin/unified-balance-kit exposes the same methods on the kit instance without the App Kit unifiedBalance namespace.

When to use Gateway directly

Use Gateway contracts and APIs directly when a flow needs more control than spend() exposes, or when the capability is not on the kit surface yet.

• Custom attestation handling or multi-intent burn sets
• Low-level burn-intent or TransferSpec fields the kit does not expose (for example maxBlockHeight or salt)
• Direct REST or contract integration without the TypeScript SDK
• Contract- or API-level debugging and experimentation
• Capabilities outside deposit, balance, estimate, and spend, for example, nanopayments and x402 batch APIs (/v1/batch/submit, /v1/x402/*)

With direct Gateway integration, you assemble deposit, burn intent, transfer submission, and destination execution yourself. With forwarding, Circle Forwarding Service submits the destination mint; you track status via transferId instead of calling the minter yourself.

Confirm behavior against your route and SDK version before relying on this list.

Further reading and implementation resources

• App Kit: Unified Balance — install, method reference, and examples
• Unified Balance fees — fee composition for estimateSpend() and spend()
• Gateway overview — deposit, burn intent, attestation, and mint flow
• Gateway Forwarding Service — enableForwarder=true behavior and polling
• Gateway API reference — /v1/balances, /v1/transfer, /v1/estimate, and related endpoints

For walkthroughs with code, see the Unified Balance Kit launch post and the Unified Balance Kit technical series.