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

# How-to: Retire existing wallets

> Retire dev-controlled wallets from active use by sweeping balances, re-tagging metadata, and blocking further activity with Compliance Engine policies.

Dev-controlled wallets are persistent onchain accounts. Circle's API does not
provide a delete, disable, or archive endpoint for individual wallets or for
wallet sets, and there is no bulk delete operation. Once a wallet is created,
its address and key material remain part of your wallet set. Use this guide to
retire a wallet from active use while keeping it available for audit and
reconciliation.

## Prerequisites

Before you begin, ensure that you've:

* Created a
  [Circle Developer Account and an API key](/w3s/circle-developer-account).
* Generated and registered an entity secret using the
  [Circle Console](https://console.circle.com/wallets/dev/configurator/entity-secret)
  or the
  [SDK](/wallets/dev-controlled/register-entity-secret#create-an-entity-secret-using-the-sdk).
* Created at least one dev-controlled wallet. If you haven't, complete the
  [Create a dev-controlled wallet](/wallets/dev-controlled/create-your-first-wallet)
  quickstart.
* Identified the `id` of each wallet you want to retire.

## Steps

<Steps>
  <Step title="Sweep any balance">
    Send all token and native balances to another wallet you control before
    stopping use of the wallet. See [Transfer tokens across
    wallets](/wallets/dev-controlled/transfer-tokens-across-wallets) for the
    transfer flow.
  </Step>

  <Step title="Re-tag the wallet">
    Call [Update a
    wallet](/api-reference/wallets/developer-controlled-wallets/update-wallet)
    (`PUT /wallets/{id}`) and update the `name` and `refId`. For example, prefix
    `refId` with `archived-` so your application can filter the wallet out of
    active lists. The wallet remains available to query for audit and
    reconciliation.
  </Step>

  <Step title="Stop using the wallet in your application">
    Remove the wallet's `id` and `refId` from any user record or assignment pool
    so it is no longer used for new transactions.
  </Step>

  <Step title="Block further activity with policies">
    Use the [Compliance Engine](/wallets/compliance-engine) to screen and deny
    transactions on retired wallets, or enforce equivalent rules in your own
    backend before submitting transactions.
  </Step>
</Steps>

<Note>
  There is no batched delete or disable endpoint. To retire many wallets at
  once, iterate the same flow over a list of wallet IDs in your code: sweep,
  re-tag with `PUT /wallets/{id}`, then remove each wallet from active
  assignment in your application.
</Note>