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

# Non-custodial accounts

> Non-custodial accounts are Digital Asset Accounts where the end customer holds the assets and approves every debit with a key on their own device

> [!NOTE]
>
> Non-custodial accounts are available in sandbox only. Production non-custodial
> accounts are on the roadmap.

A non-custodial account is a Digital Asset Account that the end customer
controls. The assets sit in the end customer's own onchain wallet, and every
debit needs the end customer's approval from a key on their own device. Neither
Circle nor your backend can move funds from the account without that approval.
To create one, see
[Create a non-custodial account](https://developers.circle.com/digital-asset-accounts/quickstarts/create-non-custodial-account.md).

## What's different from a custodial account

A non-custodial account is a Digital Asset Account with a `custodyType` of
`self`. Your integration differs from a custodial account in these ways:

* **The end customer approves every debit**: transfers, withdrawals, and account
  creation carry the end customer's signature in the `X-Device-Authorization`
  header. Your API key still authenticates every request, but it can't approve a
  debit on its own.
* **Requests come from your application**: the
  [React Native SDK](https://developers.circle.com/sdks/daa/react-native-sdk.md) builds and signs each request
  in your application, and your backend relays it to Circle with your API key.
* **The end customer signs in and registers a key**: you onboard the end
  customer first, as for a custodial account. The end customer then signs in
  with social login and registers an authorization key on their device.
* **The end customer creates the account**: the end customer signs the create
  request. Circle doesn't create a non-custodial account when KYB is approved.
* **One wallet on one blockchain**: the account holds USDC and EURC in one
  onchain wallet on its home blockchain.

For a side-by-side comparison, see
[Account structure](https://developers.circle.com/digital-asset-accounts/concepts/account-structure.md#custodial-and-non-custodial-accounts).

## How a debit is approved

Every transfer or withdrawal from a non-custodial account carries a fresh
signature from the end customer's authorization key. The signature covers the
exact request, so a request that's changed after the end customer approves it
fails.

```mermaid theme={null}
sequenceDiagram
    participant User as End customer's device
    participant Backend as Your backend
    participant Circle as Circle system
    participant Signer as Circle TEE enclave
    participant Chain as Blockchain

    User->>User: Approve with biometrics
    Note over User: Authorization key signs the exact request
    User->>Backend: Signed request
    Backend->>Circle: Same bytes, plus your API key
    Circle->>Signer: Signed request
    Note over Signer: Verifies the end customer's signature
    Signer-->>Circle: Wallet signature for this request only
    Circle->>Chain: Submit transaction
```

1. Your application asks the end customer to approve the request. Their device
   unlocks the authorization key with biometrics, or the screen lock on an
   iPhone, and the key signs the exact request.
2. Your backend relays the signed request to Circle without changing it, and
   adds your API key.
3. Circle's system passes the request to the Circle TEE enclave. The enclave
   checks the end customer's signature and produces a wallet signature for that
   request only.
4. Circle submits the transaction to the blockchain.

The enclave runs in a trusted execution environment (TEE): a hardware-isolated
environment that runs only approved code, which Circle verifies before the
enclave can use any key material. Circle's system carries the request to the
enclave but can't change it. Your API key, Circle's system, and social login
can't produce a valid request on their own.

## The authorization key

The authorization key is the key that approves every debit. It has these
properties:

* **Held by the end customer**: the private key is created on the end customer's
  device and never leaves it.
* **Hardware-backed**: the device's secure key hardware stores the key, and the
  key can't be exported.
* **Approved per use**: the device asks the end customer to confirm before each
  signature. On an Android-powered device, the end customer must use a strong
  biometric, such as a fingerprint or face unlock. A PIN, pattern, or password
  doesn't work. On an iPhone, Face ID, Touch ID, or the screen lock works.

An end customer can register a key on more than one device. Each device signs in
with social login and adds its own key.

The following devices are supported:

| Platform | Key storage | Integration |
| - | - | - |
| iOS | Secure Enclave | [React Native SDK](https://developers.circle.com/sdks/daa/react-native-sdk.md) |
| Android | StrongBox, or other hardware-backed key storage | [React Native SDK](https://developers.circle.com/sdks/daa/react-native-sdk.md) |
| Web browser | Not available | Not available |

Simulators, emulators, and devices without secure key hardware can't create an
authorization key.

## Who does what

| Part | Responsibility |
| - | - |
| Your application | Runs your own social sign-in, holds the authorization key through the SDK, and asks the end customer to approve each write |
| Your backend | Completes onboarding for the end customer, and relays each SDK request to Circle with your API key, without changing its bytes. It must also check every request against the signed-in user. See [Set up a backend relay](https://developers.circle.com/digital-asset-accounts/quickstarts/create-non-custodial-account.md#step-1-set-up-a-backend-relay) |
| Circle | Verifies the login and the end customer's signature, provisions the wallet, and submits the blockchain transaction |

Your backend must onboard the end customer before they sign in. Login links the
end customer to an existing `clientEntityId`. It never creates one. See
[Onboard customers](https://developers.circle.com/digital-asset-accounts/quickstarts/onboard-customers.md).

## Home blockchain and balance

Each non-custodial account has one onchain wallet on one home blockchain. You
choose it with the `blockchain` field when you create the account, which
defaults to `ARC`, and you can't change it later. Not every blockchain is
available in every environment, and an unavailable one returns `400`. See
[Create an account](https://developers.circle.com/api-reference/digital-asset-accounts/all/create-account.md).
The account balance shows the home wallet only.

## Network fees

The end customer doesn't need native tokens to pay network fees for
non-custodial account transactions.

## Limitations in the sandbox preview

| Capability | Status |
| - | - |
| Login methods | Google sign-in only. Other social providers, your own custom authentication, and email one-time codes aren't available |
| Devices | iOS and Android through the React Native SDK only |
| Lost-device recovery | Not available. A new device repeats social login and adds a new key. Earlier keys stay registered |
| Authorization key revocation | Not available |
| Deposits from a blockchain other than the home blockchain | Not available. Deposit address requests for other blockchains are rejected |
| Crosschain USDC transfers | Available only when Circle enables them for you |
| Earn, Swap, and Cards | Not available |
| Account update and archive from the SDK | Not available |

> [!WARNING]
>
> A lost device doesn't lock the account. The end customer signs in with the same
> Google Account on a new device and registers a new key. The lost device's key
> stays registered, because keys can't be revoked in the sandbox preview. If the
> end customer loses access to their Google Account and every registered device,
> Circle can't restore their access to debits. Tell your users before they fund
> the account.