Skip to main content
Use Circle-hosted dev-controlled wallets 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. If you custody keys yourself, see Bring your own wallet for CPN.

​
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 or Create an onchain transaction.
Dev-controlled Programmable Wallets are documented in the Circle Wallets section. This topic frames those capabilities for CPN payments only.

​
Prerequisites

Before you begin:
Mainnet access for Programmable Wallets is typically granted after your CPN eligibility application is approved, when Circle Wallets was requested as a capability.

​
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:
Follow Register your 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.

​
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: Example request body for a single sandbox EOA on Sepolia (adjust names and ciphertext for your environment): 1. Create wallet set - example request body: 
{
  "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: 
{
  "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. For Transactions V1 on EVM testnet, use EVM-TESTNET instead. On mainnet, set blockchains to the production identifier that matches your CPN corridor (for example, ETH for Ethereum mainnet). See 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 and add or update your subscriber configuration as offered for your organization.
  2. For Programmable Wallets subscription details and payload shapes, see Webhook notifications, Webhook notification flows, and Create subscription (POST /v2/notifications/subscriptions). Common event types include transactions.inbound and transactions.outbound.

​
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 to obtain testnet USDC. Enter your wallet address and select the matching testnet blockchain. For Transactions V1 on EVM, ensure you also have testnet native gas tokens (check the faucet for your target 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. You can exercise the Circle APIs flow in sandbox before switching to production endpoints.
Confirm funding with 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