> ## 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-account architecture

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

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

* Most teams create one sub-account per merchant or segment. Then USDC balances
  and activity stay easy to trace in your books and in Circle reports.
* Every setup also includes a main wallet. USDC can live in the main wallet
  only, in sub-accounts only, or across both, depending on how you fund and pay
  out.

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

## Wallet structure and typical flows

The following figure is a simplified model of a Managed Payments integration
with sub-accounts. 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-account A]
    SB[Sub-account 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-account before payout.

## Accounts API

<Note>
  If you use the direct onboarding model, Circle handles the creation of
  sub-accounts for you. Submit end-merchant KYB through the [Partner Onboarding
  API reference](/api-reference/circle-mint/onboarding/list-applications), and
  Circle creates sub-accounts on your behalf after approval.
</Note>

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

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

Each sub-account has both an `accountId` and a `walletId`. Both IDs point to the
same sub-account. The `accountId` names the stablecoin account record. The
`walletId` names the wallet that holds the account's USDC balance. API requests
and responses use one or both, depending on the endpoint.

Circle grants role-based API access when you onboard. The endpoints your API
keys can call depend on the roles set for 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-accounts during onboarding. In both cases, you reference the same
`accountId` values for wires, payouts, and payins.

## Sub-account lifecycle

Use a sub-account's `status` to determine whether it can process activity:

* `pending`: Circle is creating the sub-account, but it isn't operational yet.
* `active`: The sub-account can process supported activity.
* `rejected`: Circle rejected the sub-account creation request, and the
  sub-account can't be used.
* `archived`: The sub-account is retired and excluded from account listings by
  default. Read requests still work, but most requests that change the account
  are blocked.

To retire an active sub-account, first reduce all of its balances to zero. Then
[archive the account](/api-reference/cpn/managed-payments/accounts/archive-account).
The request is idempotent, so you can safely retry it. To retrieve archived
sub-accounts, list accounts with the `status=archived` query parameter.

Archiving doesn't permanently close a sub-account. An incoming deposit to an
existing deposit address or wire instruction automatically returns the
sub-account to `active` status. After you archive a sub-account, stop sending
funds to its existing deposit details if you intend to keep it retired.

## Funding and pooled balances

Depending on your setup, USDC can be funded and spent across the main wallet and
sub-accounts in several ways:

* Wires can credit one sub-account 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-account before they go onchain.
  Terms follow your agreement with Circle.
* Payouts usually debit a sub-account balance. If your integration supports it,
  you can fund payouts from the main wallet instead of from each sub-account.
  That helps when you send a lot and don't want USDC in every sub-account first.
  Use that path only when your setup supports it.

## Payins and payouts

Handle payins, debits, and reconciliation per sub-account:

* **Payins (receiving USDC):** Each sub-account 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-account to debit when you create a payout.

<Note>
  The two money-out endpoints expect different `source.type` tokens for the same
  sub-account: [create a
  payout](/api-reference/cpn/managed-payments/payouts/create-payout) (`POST
      /v1/payouts`) requires `source.type` = `wallet` with the `walletId`, while
  [create a
  withdrawal](/api-reference/cpn/managed-payments/withdrawals/create-account-withdrawal)
  (`POST /v1/accounts/withdrawals`) requires `source.type` = `account` with the
  `accountId`.
</Note>

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