> ## 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: Set up a Circle wallet for CPN payments

> Configure a Circle-hosted dev-controlled wallet as your operational wallet for CPN onchain payment flows.

Use Circle-hosted [dev-controlled wallets](/wallets/dev-controlled.mdx) as your
operational wallet for CPN onchain payment flows. Circle custody keeps signing
keys secure and surfaces the wallet address and wallet ID through the Wallet
APIs.

Treasury is your responsibility: fund the wallet on the right blockchain,
reconcile balances, and size liquidity for your payment volume. When Circle also
moves your fiat and USDC, pair this guide with
[Set up Circle on/off-ramps for CPN payments](/cpn/guides/circle-liquidity/setup-circle-on-off-ramps-for-cpn-payments).
If you custody keys yourself, see
[Bring your own wallet for CPN](/cpn/concepts/wallets/bring-your-own-wallet).

## Overview

* Use this guide when you want Circle to host the wallet that signs CPN onchain
  transactions for USDC transfers.
* CPN does not require Circle-hosted wallets. The steps here are optional; they
  support teams that want Circle custody for the sender wallet.
* After your wallet holds USDC on the required blockchain, you can continue with
  [Integrate with CPN as an OFI](/cpn/quickstarts/integrate-with-cpn-ofi) or
  [Create an onchain transaction](/cpn/guides/transactions/create-an-onchain-txn).

<Note>
  Dev-controlled Programmable Wallets are documented in the [Circle
  Wallets](/wallets) section. This topic frames those capabilities for CPN
  payments only.
</Note>

## Prerequisites

Before you begin:

* You have a [CPN Console](https://cpn.circle.com/signin) account with the
  [Circle Wallet](/wallets/dev-controlled) capability enabled for your
  organization.
* You have an API key for Programmable Wallets. Create and manage keys in
  [CPN Console → Developer → API Keys](https://cpn.circle.com/signin).
* You have sandbox or mainnet access enabled for Programmable Wallets.

<Note>
  Mainnet access for Programmable Wallets is typically granted after your CPN
  eligibility application is approved, when **Circle Wallets** was requested as
  a capability.
</Note>

## Steps

This guide covers generating and registering your entity secret, creating a
wallet set and EOA wallet, configuring notifications, and funding the wallet
with USDC.

### Step 1. Generate and register your entity secret

The entity secret is a 32-byte value that secures your developer-controlled
wallets. Circle never stores the secret in plain text: you must protect it.

Register your entity secret:

<Tabs>
  <Tab title="Using the SDK">
    Follow
    [Register your entity secret](/wallets/dev-controlled/register-entity-secret)
    for Node.js and Python: install the SDK, generate the entity secret, and
    register the ciphertext with Circle. That guide includes tabs for each language.
    Use environment variables or a secrets manager for `apiKey` and `entitySecret`;
    never commit real values.
  </Tab>

  <Tab title="Without the SDK">
    Generate a cryptographically random 32-byte value and store it in a secure
    location (for example in a secrets manager). From a terminal you can use:

    ```bash theme={null}
    openssl rand -hex 32
    ```

    Encrypt the secret with Circle's public key, then register the ciphertext with
    the Programmable Wallets configuration API. Read
    [Entity secret management](/wallets/dev-controlled/entity-secret-management) for
    encryption, ciphertext, and non-SDK options, including the sample repository
    linked from that topic.

    The HTTP API uses `POST /v1/w3s/config/entity/entitySecret` with a body
    containing `entitySecretCiphertext`. Store the recovery file from the response
    if you need to recover access later.
  </Tab>
</Tabs>

### Step 2. Create a wallet set and operational wallet

A wallet set groups wallets under one entity secret. Create a wallet set, then
create at least one externally owned account (EOA) wallet.

Use the API reference for request and response fields:

* [Create wallet set](/api-reference/wallets/developer-controlled-wallets/create-wallet-set)
  (`POST /v1/w3s/developer/walletSets`)
* [Create wallet](/api-reference/wallets/developer-controlled-wallets/create-wallet)
  (`POST /v1/w3s/developer/wallets`)

Example request body for a single sandbox EOA on Sepolia (adjust names and
ciphertext for your environment):

**1. Create wallet set** - example request body:

```json theme={null}
{
  "name": "CPN Operational Wallets",
  "entitySecretCiphertext": "<your_encrypted_entity_secret>"
}
```

**2. Create wallet** - example request body for the second call. Replace
`<your_wallet_set_id>` with the `walletSetId` from the create-wallet-set
response:

```json theme={null}
{
  "idempotencyKey": "<unique_key>",
  "entitySecretCiphertext": "<your_encrypted_entity_secret>",
  "walletSetId": "<your_wallet_set_id>",
  "blockchains": ["ETH-SEPOLIA"],
  "count": 1,
  "accountType": "EOA"
}
```

Save the **wallet ID** and **address** from the create-wallet response. CPN uses
the wallet ID for transaction APIs; funding flows use the address.

Use `ETH-SEPOLIA` for typical Transactions V2 sandbox testing, or `ARC-TESTNET`
to test on Arc Testnet. For Transactions V1 on EVM testnet, use `EVM-TESTNET`
instead (Arc does not support Transactions V1). On mainnet, set `blockchains` to
the production identifier that matches your CPN corridor (for example, `ETH` for
Ethereum mainnet or `ARC` for Arc mainnet). See
[Supported blockchains](/cpn/references/blockchains/supported-blockchains).

### Step 3. Configure webhook notifications for wallet activity

Subscribe to wallet and transaction events so your system is notified when funds
arrive or transfers complete.

1. Open [CPN Console → Developer → Webhooks](https://cpn.circle.com/signin) and
   add or update your subscriber configuration as offered for your organization.
2. For Programmable Wallets subscription details and payload shapes, see
   [Webhook notifications](/api-reference/webhooks),
   [Create subscription](/api-reference/wallets/common/create-subscription)
   (`POST /v2/notifications/subscriptions`), and the
   [`transactions.inbound`](/api-reference/wallets/common/transactions-inbound)
   and
   [`transactions.outbound`](/api-reference/wallets/common/transactions-outbound)
   webhook events.

### Step 4. Fund your wallet with USDC

Your operational wallet must hold USDC before you initiate a CPN payment that
draws from that wallet.

* **Sandbox:** Use the [Circle faucet](https://faucet.circle.com/) to obtain
  testnet USDC. Enter your wallet address and select the matching testnet
  blockchain.
* **Mainnet:** Fund the wallet by moving USDC from your Circle business account
  balance (for example after an on-ramp). Follow how to
  [Set Up Circle On/Off-Ramps for CPN Payments](/cpn/guides/circle-liquidity/setup-circle-on-off-ramps-for-cpn-payments).
  You can exercise the Circle APIs flow in sandbox before switching to
  production endpoints.

Confirm funding with
[List wallet balance](/api-reference/wallets/developer-controlled-wallets/list-wallet-balance)
(`GET /v1/w3s/wallets/{id}/balances`). When your USDC balance is sufficient for
your test or production payment, you are ready to call CPN transaction APIs.

## See also

* [Integrate with CPN as an OFI](/cpn/quickstarts/integrate-with-cpn-ofi)
  (continue at Part 1: Request a quote).
* [Set up Circle on/off-ramps for CPN payments](/cpn/guides/circle-liquidity/setup-circle-on-off-ramps-for-cpn-payments)
  (fund your operational wallet via Circle Mint).
* [Set up a webhook endpoint](/api-reference/webhook-endpoints) (CPN payment
  events)
* [Webhook events](/cpn/references/webhooks/webhook-events)
* [Entity secret management](/wallets/dev-controlled/entity-secret-management)