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

# 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 sandbox testing. On mainnet, set `blockchains` to the
production identifier that matches your CPN corridor (for example, `ETH` for
Ethereum 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)