- Most teams create one sub-wallet per merchant or segment. Then USDC balances and activity stay easy to trace in your books and in Circle reports.
- Your setup has a main wallet too. USDC can live in the main wallet only, in sub-wallets only, or across both. It depends on how you fund and pay out.
Wallets structure and typical flows
The following figure is a simplified model. Circle enables only the paths that your setup and agreement support. Solid arrows are typical funding, receive, and payout paths, including payouts funded from the main wallet. Dotted arrows are optional paths your setup may use, such as a line of credit into the main wallet or moving USDC to a sub-wallet before payout.Accounts API
If you use the Direct onboarding model, you can skip this section. In that
model, Circle creates sub-wallets on your behalf.
- Create a managed payments intermediary account when you add a merchant sub-wallet in the Intermediary onboarding model.
- List accounts to page through sub-wallets and see each one’s balances and metadata.
- Get an account to
load one sub-wallet’s stablecoin account by
accountId, including balances and metadata.
accountId
values for wires, payouts, and payins.
Balances API
Use the Balances API when you want available and unsettled USDC for a sub-wallet (or across sub-wallets) without the full account payload.- List account balances
to read balances for all sub-wallets, or filter to one sub-wallet by passing
its
accountIdas a query parameter. - Get an account balance
to read balances for a single sub-wallet by its
accountIdpath parameter.
accountId here as for that sub-wallet’s payouts, payins, and
wires. Teams often call these endpoints on a schedule or before a large payout
to reconcile books or confirm available USDC.
Funding and pooled balances
Depending on your setup, USDC can be funded and spent across the main wallet and sub-wallets in several ways:- Wires can credit one sub-wallet so that merchant’s USDC sits in its own balance. Use the Wires API for bank accounts and wire instructions.
- If your setup allows it, you can mint to a shared main wallet instead. That pool can back steady, high-volume payout use cases.
- Some setups include a line of credit. USDC may land in the main wallet first; payouts can move funds to the correct sub-wallet before they go onchain. Terms follow your agreement with Circle.
- Payouts usually debit a sub-wallet balance. If your integration supports it, you can fund payouts from the main wallet instead of from each sub-wallet. That helps when you send a lot and don’t want USDC in every sub-wallet first. Use that path only when your setup supports it.
Payins, payouts, and reconciliation
Handle payins, debits, and reconciliation per sub-wallet:- Payins (receiving USDC): Each sub-wallet can have a stable onchain address. Create a continuous payment intent so that each merchant or segment has a dedicated receive address.
- Payouts and withdrawals: Specify the
walletIdoraccountIdof the sub-wallet to debit when you create a payout. - Daily reconciliation: Query the Balances API on a schedule (for example, once per day or before large payouts) and compare the returned balances against your internal ledger. Circle also provides downloadable settlement reports that include per-sub-wallet transaction history, timestamps, and status fields you can use for automated matching.
| Activity | API / resource | Key identifier |
|---|---|---|
| Receive USDC | Continuous payment intent | paymentIntentId, onchain address |
| Send USDC | Payouts API | walletId or accountId |
| Check balances | Balances API | accountId |
| Match transactions | Settlement reports | accountId, transaction timestamps |