Skip to main content
Circle Payments Network (CPN) runs in two environments: mainnet and testnet. Mainnet moves real money between real institutions. Testnet simulates payments with mock counterparties, for development and testing. Both share the same API, so most of your code works unchanged between them. A few key behaviors still diverge.

​
Determine your environment

CPN doesn’t use separate URLs for mainnet and testnet. Every request goes to the same base URL. Your API key sets the environment:
  • Keys prefixed TEST_API_KEY authenticate testnet requests.
  • Keys prefixed LIVE_API_KEY authenticate mainnet requests.

​
Blockchain identifiers differ per environment

Every blockchain has a separate mainnet and testnet identifier. For example, Ethereum uses ETH and ETH-SEPOLIA. Polygon PoS uses MATIC and MATIC-AMOY. Solana uses SOL and SOL-DEVNET. See Supported blockchains for the full list of supported blockchains. The blockchain value in a request must match your API key’s environment. A mainnet identifier with a testnet key, or the reverse, is rejected with a validation error. Mainnet and testnet run on separate networks. Related values differ too: token and contract addresses (see Payment smart contract addresses) and transaction hashes. An OFI can reuse the same wallet address across environments, but its balance and transaction history are tracked separately per network. CPN broadcasts a real onchain USDC transfer in both environments. On testnet, that transfer settles on a testnet blockchain, so the USDC involved has no real-world value.

​
Payment settlement differs end-to-end

The biggest difference is what happens on the fiat leg, when a payment reaches the Beneficiary Financial Institution (BFI):
  • On mainnet, a payment settles to a real BFI. It pays out real fiat, using real travel rule, beneficiary bank, and request for information (RFI) data.
  • On testnet, a payment never reaches a real BFI. No real travel rule data is exchanged, and no real fiat payout occurs.
Because the final payout is mocked, some settlement artifacts are mocked too. For example, a payment’s fiatNetworkPaymentRef doesn’t point to a real fiat network on testnet.

​
Simulate outcomes with magic values

Testnet doesn’t route to a real BFI. Instead, CPN offers magic values that trigger a chosen outcome. Use them to test how your integration handles each payment stage. No real counterparty is needed. Magic values only work on testnet. On mainnet, CPN treats them as plain input.

​
Validation and data differ by environment

  • Testnet payments never reach a real institution. Use synthetic travel rule, beneficiary bank, and RFI data. Don’t use real personal or business information.
  • Request checks, such as required fields, formats, and limits, mirror mainnet closely. This keeps testnet reliable for integration tests.
  • Pricing on testnet is approximate. Testnet tokens have no real market value:
    • Exchange rates are a rough estimate from mainnet market data. Expect the same trade to price differently on mainnet.
    • Gas rates on testnet are real, but testnet-specific. They move on their own. Don’t use testnet fees to predict mainnet fees.

​
Summary