> ## Documentation Index
> Fetch the complete documentation index at: https://developers.circle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sub-wallet architecture

> Sub-wallets, your main wallet, and how they work together in Managed Payments

A Managed Payments sub-wallet is a separate ledger for a merchant or segment. It
belongs to your Circle Managed Payments Account for your setup.

* 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.

Together these wallets let you split balances for books and reports while still
using shared funding or pooled sends when your setup allows.

## Wallets structure and typical flows

The following figure is a simplified model. Circle enables only the paths that
your setup and agreement support.

```mermaid theme={null}
flowchart TB
  subgraph mp_setup["Managed Payments setup"]
    MW[Main wallet]
    SA[Sub-wallet A]
    SB[Sub-wallet B]
  end

  Wire[Fiat wire] --> MW
  Wire --> SA
  LOC[Line of credit] -.-> MW
  MW -.-> SA

  SA --> Payin[Payment intent receive]
  SB --> Payin
  SA --> Payout[USDC payout]
  SB --> Payout
  MW --> Payout
```

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

<Note>
  If you use the **Direct** onboarding model, you can skip this section. In that
  model, Circle creates sub-wallets on your behalf.
</Note>

Use the Digital Asset Accounts API to create and inspect the stablecoin account
that backs each merchant sub-wallet.

* [Create a managed payments intermediary account](/api-reference/cpn/managed-payments/accounts/create-account)
  when you add a merchant sub-wallet in the Intermediary onboarding model.
* [List accounts](/api-reference/cpn/managed-payments/accounts/list-accounts) to
  page through sub-wallets and see each one's balances and metadata.
* [Get an account](/api-reference/cpn/managed-payments/accounts/get-account) to
  load one sub-wallet's stablecoin account by `accountId`, including balances
  and metadata.

Sub-wallet activity in API requests and responses references these account and
wallet IDs. Circle grants role-based API access during onboarding; the endpoints
available to your API keys depend on the roles assigned to your account.

In the Intermediary model, you call the
[create account](/api-reference/cpn/managed-payments/accounts/create-account)
endpoint after each merchant is approved. In the Direct model, Circle provisions
sub-wallets during onboarding. In both cases, you reference the same `accountId`
values for wires, payouts, and payins.

## 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](/api-reference/cpn/managed-payments/wires/create-account-wire-account)
  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 and payouts

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 `walletId` or `accountId` of the
  sub-wallet to debit when you create a payout.

| Activity           | API / resource            | Key identifier                      |
| ------------------ | ------------------------- | ----------------------------------- |
| Receive USDC       | Continuous payment intent | `paymentIntentId`, onchain address  |
| Send USDC          | Payouts API               | `walletId` or `accountId`           |
| Match transactions | Settlement reports        | `accountId`, transaction timestamps |