> ## 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 Circle on/off-ramps for CPN payments

> Use Circle APIs to move fiat and USDC in support of CPN payment flows (onramp liquidity and optional offramp).

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](/circle-mint/quickstarts/getting-started)
  for authentication and environments.

<Note>
  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.
</Note>

## Prerequisites

Before you begin, ensure you have:

* A [CPN Console](https://cpn.circle.com/signin) 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](https://cpn.circle.com/signin).
* 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](/cpn/guides/wallets/setup-circle-wallet-for-cpn-payments);
  otherwise use your own wallet infrastructure.

<Note>
  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](/circle-mint/references/sandbox-and-testing) 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.
</Note>

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

### Step 1: Link your bank account

Register the bank account you use to send fiat deposits. Use
[Create wire bank account](/api-reference/circle-mint/account/create-business-wire-account)
(`POST /v1/businessAccount/banks/wires`). For a guided walkthrough, see
[Deposit Fiat](/circle-mint/howtos/deposit-fiat).

### Step 2: Retrieve wire instructions and send funds

Retrieve instructions with
[Get wire transfer instructions](/api-reference/circle-mint/account/get-business-wire-account-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](/api-reference/circle-mint/account/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](/api-reference/circle-mint/account/list-business-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](/api-reference/circle-mint/general/create-subscription)
(`POST /v1/notifications/subscriptions`). The request body requires a public
HTTPS endpoint that can complete the
[AWS SNS subscription handshake](https://docs.aws.amazon.com/sns/latest/dg/sns-http-https-endpoint-as-subscriber.html)
(see
[Set up a webhook endpoint](/api-reference/webhook-endpoints#v1-notifications)):

```json theme={null}
{
  "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](/circle-mint/references/webhook-notifications) for
payload shapes.

You can also manage subscriber endpoints in
[CPN Console → Developer → Webhooks](https://cpn.circle.com/signin) 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](/api-reference/circle-mint/account/create-business-recipient-address)
(`POST /v1/businessAccount/wallets/addresses/recipient`), then send USDC onchain
with
[Create transfer](/api-reference/circle-mint/account/create-business-transfer)
(`POST /v1/businessAccount/transfers`). Track completion with
[Get transfer](/api-reference/circle-mint/account/get-business-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):

```json theme={null}
{
  "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`:

```json theme={null}
{
  "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](/api-reference/circle-mint/account/get-business-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](/api-reference/circle-mint/error-codes#transfer-error-codes) and
[Idempotent requests](/circle-mint/references/sandbox-and-testing#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.

### Step 1: Link your bank account

Use
[Create wire bank account](/api-reference/circle-mint/account/create-business-wire-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](/api-reference/circle-mint/account/create-business-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):

```json theme={null}
{
  "idempotencyKey": "<unique_key>",
  "currency": "USD",
  "chain": "ETH"
}
```

### Step 3: Configure notifications for inbound activity

Subscribe with
[Create subscription](/api-reference/circle-mint/general/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](/circle-mint/references/webhook-notifications). For
example, `transfers` notifications reflect onchain transfer status changes.
Where available, you can configure endpoints in
[CPN Console → Developer → Webhooks](https://cpn.circle.com/signin), in addition
to using the API.

CPN payment lifecycle events still use CPN subscriptions (see
[Webhook events](/cpn/references/webhooks/webhook-events)).

### Step 4: Offramp USDC to your bank account

Verify your balance with
[List balances](/api-reference/circle-mint/account/list-business-balances)
(`GET /v1/businessAccount/balances`), then create a payout with
[Create payout](/api-reference/circle-mint/account/create-business-payout)
(`POST /v1/businessAccount/payouts`).

Example body (see the API reference for all required fields):

```json theme={null}
{
  "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](/api-reference/circle-mint/account/get-business-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](/api-reference/circle-mint/error-codes#payout-error-codes) and
[Idempotent requests](/circle-mint/references/sandbox-and-testing#idempotent-requests).

## See also

* With your operational wallet funded, return to
  [Integrate with CPN as an OFI](/cpn/quickstarts/integrate-with-cpn-ofi) at
  Part 1: Request a quote.
* [Set up a Circle Wallet for CPN payments](/cpn/guides/wallets/setup-circle-wallet-for-cpn-payments)
  for operational wallet setup with Circle dev-controlled wallets.