Skip to main content
This guide shows how to use Circle Mint account APIs for CPN payment flows when using Circle for treasury and settlement. Use it to onramp fiat into USDC and fund your operational wallet, and to offramp USDC to fiat when you need to.

​
Overview

  • Use this guide when you want Circle to supply USDC liquidity (fiat in, USDC to your operational wallet) or to offramp USDC to fiat.
  • CPN does not require Circle on/off-ramps. You can source USDC from any compliant channel that meets your compliance and settlement needs.
  • Circle on/off-ramp behavior is provided by Circle APIs (Circle Mint and related account APIs). Start with Getting started with the Circle APIs for authentication and environments.
Each step links to the Circle Mint API reference page for that operation, where request and response fields are fully defined. The steps map those Circle APIs to CPN scenarios.

​
Prerequisites

Before you begin, ensure you have:
  • A CPN Console account with the Circle On/Off-Ramps capability enabled for your organization (after your CPN eligibility application is approved).
  • An API key with Circle On/Off-Ramps (Circle APIs) permissions. Create and manage keys in CPN Console → Developer → API Keys.
  • Sandbox or mainnet access enabled for Circle On/Off-Ramps.
  • An operational wallet address for USDC. To use a Circle wallet, see Set up a Circle Wallet for CPN payments; otherwise use your own wallet infrastructure.
Mainnet access for Circle On/Off-Ramps is typically granted after your CPN eligibility application is approved and you request that capability. Sandbox uses the same request and response structure as production.This guide uses Circle Mint account APIs. For Mint, use the sandbox and production API hosts and the API key for each environment. CPN Platform payment APIs use one base URL: the API key determines whether requests run in sandbox or production.

​
Onramp: Deposit fiat and transfer USDC to your operational wallet

As an Originating Financial Institution (OFI), you convert fiat to USDC and move USDC to the wallet that signs CPN onchain transfers. Register the bank account you use to send fiat deposits. Use Create wire bank account (POST /v1/businessAccount/banks/wires). For a guided walkthrough, see Quickstart: Deposit via funds transfer.

​
Step 2: Retrieve wire instructions and send funds

Retrieve instructions with Get wire transfer instructions (GET /v1/businessAccount/banks/wires/{id}/instructions). Send the wire from your bank. Include the tracking reference (or equivalent memo) Circle provides so the deposit can be matched to your account. In sandbox, simulate a deposit with Create mock wire payment (POST /v1/mocks/payments/wire). Mock wires can take up to 15 minutes to process.

​
Step 3: Confirm your Circle business account balance

After the deposit is credited, confirm USDC with List balances (GET /v1/businessAccount/balances).

​
Step 4: Configure notifications for deposit status (optional)

Optionally subscribe to status notifications so your backend learns when a deposit completes. Use Create subscription (POST /v1/notifications/subscriptions). The request body requires a public HTTPS endpoint that can complete the AWS SNS subscription handshake (see the API reference and Notifications quickstart): 
{
  "endpoint": "https://your-endpoint.example.com/webhooks"
}
Notification payloads use a notificationType field. For flows in this guide, common values include transfers (onchain transfers) and payouts (bank payouts); see Notifications data models for payload shapes. You can also manage subscriber endpoints in CPN Console → Developer → Webhooks when your organization exposes that UI for your Circle APIs integration.

​
Step 5: Transfer USDC to your operational wallet

Allowlist your operational wallet address with Create recipient address (POST /v1/businessAccount/wallets/addresses/recipient), then send USDC onchain with Create transfer (POST /v1/businessAccount/transfers). Track completion with Get transfer (GET /v1/businessAccount/transfers/{id}). Example body for create recipient (see the API reference for all fields and valid chain values; description is required): 
{
  "idempotencyKey": "<unique_key>",
  "address": "<your_operational_wallet_address>",
  "chain": "ETH",
  "currency": "USD",
  "description": "CPN operational wallet"
}
Example body for create transfer with destination type blockchain: 
{
  "idempotencyKey": "<unique_key>",
  "source": { "type": "wallet", "id": "merchant" },
  "destination": {
    "type": "blockchain",
    "address": "<your_operational_wallet_address>",
    "chain": "ETH"
  },
  "amount": { "amount": "<usdc_amount>", "currency": "USD" }
}
When the transfer completes, your operational wallet is ready for CPN onchain steps. A successful create-transfer response returns a status of pending and a transfer id. Poll Get transfer (GET /v1/businessAccount/transfers/{id}) until the status reaches complete. If the status is failed, check the errorCode field: common values include transfer_failed, transfer_denied, and insufficient_funds. Do not reuse the same idempotencyKey for a new request with different parameters; retrying with identical parameters returns the original response. See API errors and Idempotent requests.

​
Offramp: Receive USDC and pay out to your bank account

As an OFI, you may need to offramp USDC to fiat: for example, when converting received USDC to local currency, handling payment failures, or processing returns. The steps below reverse the onramp flow: deposit USDC into your Circle business account and initiate a bank payout. Use Create wire bank account (POST /v1/businessAccount/banks/wires) for the account that will receive fiat payouts.

​
Step 2: Create a deposit address for your Circle business account

Generate an onchain deposit address with Create deposit address (POST /v1/businessAccount/wallets/addresses/deposit). USDC sent to that address credits your Circle business account balance. Example body (see the API reference for required fields and valid chain values): 
{
  "idempotencyKey": "<unique_key>",
  "currency": "USD",
  "chain": "ETH"
}

​
Step 3: Configure notifications for inbound activity

Subscribe with Create subscription (POST /v1/notifications/subscriptions) using an HTTPS endpoint as in the onramp step. Your handler receives payloads whose notificationType values are documented in Notifications data models. For example, transfers notifications reflect onchain transfer status changes. Where available, you can configure endpoints in CPN Console → Developer → Webhooks, in addition to using the API. CPN payment lifecycle events still use CPN subscriptions (see Webhook events).

​
Step 4: Offramp USDC to your bank account

Verify your balance with List balances (GET /v1/businessAccount/balances), then create a payout with Create payout (POST /v1/businessAccount/payouts). Example body (see the API reference for all required fields): 
{
  "idempotencyKey": "<unique_key>",
  "destination": {
    "type": "wire",
    "id": "<your_bank_account_id>"
  },
  "amount": { "amount": "<usdc_amount>", "currency": "USD" }
}
A successful response returns a status of pending and a payout id. Track completion with Get payout (GET /v1/businessAccount/payouts/{id}). The payout moves through pending to complete or failed. If the status is failed, check the errorCode field — common values include insufficient_funds, transaction_denied, and bank_transaction_error. See API errors and Idempotent requests.

​
See also