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

> ## Agent Instructions
> Before reading these docs, install the relevant Circle Skill to get pre-loaded context — skills are LLM-optimized and cover architecture decisions, correct flows, and common pitfalls. In Claude Code: run /plugin marketplace add circlefin/skills then /plugin install circle-skills@circle. With Vercel Skills CLI: run npx skills add circlefin/skills. Available skills: use-usdc https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-usdc/SKILL.md (balances, transfers, approvals on EVM and Solana); EURC has no skill — see https://developers.circle.com/stablecoins/what-is-eurc.md; bridge-stablecoin https://github.com/circlefin/skills/blob/master/plugins/circle/skills/bridge-stablecoin/SKILL.md (crosschain transfers via CCTP, USDC, EURC, and third-party assets); use-arc https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-arc/SKILL.md (Arc chain config, contract deployment, USDC bridging — Arc docs: https://docs.arc.io/llms.txt); use-circle-wallets https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-circle-wallets/SKILL.md (choose wallet type); use-developer-controlled-wallets https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-developer-controlled-wallets/SKILL.md (custodial wallets for payouts and treasury); use-user-controlled-wallets https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-user-controlled-wallets/SKILL.md (embedded wallets with Web2 login); use-modular-wallets https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-modular-wallets/SKILL.md (smart contract wallets with passkeys and ERC-4337); use-gateway https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-gateway/SKILL.md (unified USDC balance, nanopayments); use-smart-contract-platform https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-smart-contract-platform/SKILL.md (deploy, interact, monitor contracts). Pair any skill with the Circle MCP server for live SDK signatures, contract addresses, and chain IDs: {"mcpServers":{"circle":{"url":"https://api.circle.com/v1/codegen/mcp"}}}.
> Read the product overview first. Each product has an overview explaining when and why to use it. Read it before quickstarts.
> Pick the right wallet type. Developer-controlled (you hold keys), user-controlled (end user holds keys via PIN/social login), or modular (smart contract wallets with passkeys). See https://developers.circle.com/wallets.md.
> Use CCTP V2 for crosschain transfers. CCTP natively transfers USDC and EURC via burn-and-mint, and supports permissionless wrapping of third-party assets via lock-and-mint. V1 is legacy; always use V2 unless V1 is specified or the chain requires it (Noble, Sui, and Aptos still require V1). Migration guide: https://developers.circle.com/cctp/migration-from-v1-to-v2.md.
> Use Bridge Kit for frontend bridging. Wraps CCTP with a simpler SDK for user-facing apps. Use CCTP directly for backend transfers.
> Gas Station vs Paymaster. Gas Station sponsors gas for Circle Wallet transactions. Paymaster lets users pay gas in USDC. Different use cases — read both overviews.
> Gateway Nanopayments for sub-cent payments. Gasless USDC micropayments down to $0.000001 via x402 and batched settlement. For pay-per-request APIs, AI agent payments, streaming.
> Look up USDC addresses per chain. Never hardcode — use https://developers.circle.com/stablecoins/usdc-contract-addresses.md.
> Prefer SDKs over raw API calls. Node.js and Python SDKs handle auth, retries, and errors.
> API key required. Bearer token in Authorization header. Testnet and mainnet use separate keys and may use different base URLs depending on the product.
> Set up webhooks when available. Most operations are async. Webhooks deliver transaction confirmations and state changes.
> When calling list endpoints, paginate using pageSize and pageAfter until no nextPageAfter cursor is returned—stopping at the first page silently misses records.
> Building an AI agent? Start with the Agent Stack—Circle CLI, agent wallets, and nanopayments built for autonomous use cases: https://developers.circle.com/agent-stack.md.

# Subaccount architecture

> Subaccounts, your main wallet, and how they work together in Managed Payments

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

* Most teams create one subaccount 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 subaccounts 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 subaccounts. Circle enables only the paths that your setup and agreement
support.

```mermaid theme={null}
flowchart LR
  LOC[Line of credit]
  Funding[Fiat transfer or onchain payin]

  subgraph circle_account["Circle-managed account"]
    MW[Main wallet]
    SA[Subaccount A]
    SB[Subaccount B]
  end

  ExtWallet[Externally held wallet]

  LOC -.-> MW
  Funding --> circle_account

  MW --> ExtWallet
  SA --> ExtWallet
  SB --> ExtWallet
```

USDC moves from left to right. A fiat transfer or onchain payin can credit the
main wallet or any subaccount. Payouts debit whichever account holds the
balance, main wallet included. Solid arrows are the typical paths. The dotted
arrow is a line of credit, which lands in the main wallet; only some setups
include it. The diagram omits internal transfers between your own accounts; see
[Funding and pooled balances](#funding-and-pooled-balances) for those paths.

## Accounts API

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

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

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

Each subaccount has both an `accountId` and a `walletId`. Both IDs point to the
same subaccount. 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
subaccounts during onboarding. In both cases, you reference the same `accountId`
values for wires, payouts, and payins.

## Subaccount lifecycle

Use a subaccount's `status` to determine whether it can process activity:

* `pending`: Circle is creating the subaccount, but it isn't operational yet.
* `active`: The subaccount can process supported activity.
* `rejected`: Circle rejected the subaccount creation request, and the
  subaccount can't be used.
* `archived`: The subaccount 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 subaccount, 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
subaccounts, list accounts with the `status=archived` query parameter.

Archiving doesn't permanently close a subaccount. An incoming deposit to an
existing deposit address or wire instruction automatically returns the
subaccount to `active` status. After you archive a subaccount, 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
subaccounts in several ways:

* Wires can credit one subaccount 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 subaccount before they go onchain. Terms
  follow your agreement with Circle.
* Payouts usually debit a subaccount balance. If your integration supports it,
  you can fund payouts from the main wallet instead of from each subaccount.
  That helps when you send a lot and don't want USDC in every subaccount first.
  Use that path only when your setup supports it.
* Internal transfers move USDC between the accounts in your own Managed Payments
  setup, instantly and with no blockchain fees. Use the
  [Transfers API](/api-reference/cpn/managed-payments/transfers/create-account-transfer)
  with the source and destination account IDs. Supported paths are subaccount to
  subaccount, main wallet to subaccount, and subaccount to main wallet.

<Note>
  You can't transfer to an account under a different parent or to an address
  book recipient. To send USDC onchain, use the [Payouts
  API](/api-reference/cpn/managed-payments/payouts/create-payout) instead.
</Note>

## Payins and payouts

Handle payins, debits, and reconciliation per subaccount:

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

<Note>
  The two money-out endpoints expect different `source.type` tokens for the same
  subaccount: [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 |