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

# CPN API changes and compatibility

> Additive and breaking changes as CPN adds fields, values, events, and capabilities, and how to keep your integration compatible.

The Circle Payments Network (CPN) API evolves as Circle adds corridors, payment
methods, blockchains, compliance rules, and failure conditions. Circle
classifies API changes as backward compatible or breaking. Most
backward-compatible changes are additive: they introduce a resource, field,
value, or capability while preserving documented behavior for existing valid
requests. An Originating Financial Institution (OFI) integration must tolerate
these changes so that new response data or event types don't cause client
failures.

## Backward-compatible and breaking changes

Circle expects OFI integrations to accept the changes in the backward-compatible
column without failing or requiring an immediate update. Breaking changes alter
or remove part of the documented contract and may require integration work.

| Area | Backward-compatible change | Breaking change |
| - | - | - |
| Endpoints and resources | Add an endpoint or resource | Remove or rename an endpoint or resource |
| Requests | Add an optional parameter when omitting it preserves existing behavior | Add a required parameter, make an optional parameter required, or change the behavior when a parameter is omitted |
| Responses | Add a property | Remove or rename a property, change its data type, or make an always-present property conditionally omitted |
| Enum values | Add a value for a new condition or capability | Remove a value or change what an existing value means |
| Errors | Add an error code for a new failure condition or revise human-readable message text | Change the HTTP status or error code for an existing condition |
| Webhooks | Add an event type or a field to an existing payload | Stop emitting a documented event type, remove a field, or change an existing event's meaning |
| Validation | Relax validation so that a previously rejected request is accepted | Tighten validation so that a previously accepted request is rejected |

Use the [release notes](/release-notes) and relevant migration guides to
identify changes that require integration work. When a migration includes a
deadline, complete the required work in the communicated timeline.

## Build a tolerant integration

Backward-compatible changes don't require your integration to adopt a new
capability. They do require clients to accept response and event data that they
don't use yet.

### Optional request parameters

A new request parameter is backward compatible only when it's optional and
omitting it preserves existing behavior. Existing requests can retain their
current shape until the integration needs the capability controlled by the new
parameter.

### New response fields

Parse the response fields your integration uses and ignore unfamiliar
properties. Strict deserialization that rejects extra properties can turn an
otherwise successful API response into a client-side failure.

### General enum values

Send only documented enum values in requests. For responses, preserve any
unfamiliar raw value and map it to a neutral fallback instead of rejecting the
entire response. Storage and downstream processing must also accept unfamiliar
values.

Don't infer the meaning of an unfamiliar value or use it to trigger an
irreversible action. Add first-class handling after you confirm the value's
documented meaning.

### Lifecycle statuses

An unfamiliar lifecycle status needs a more conservative fallback than a general
enum value. Keep the resource in its current local state, preserve the raw
status, and route the record for review. Don't interpret an unfamiliar status as
success or failure, and don't release funds or take another irreversible action
based on it.

### Resource and reference IDs

The CPN OpenAPI schemas define system-generated resource IDs as UUID-formatted
strings and reference IDs as strings. Treat each identifier according to its
documented schema and as an opaque value: don't derive business meaning from its
shape or impose an undocumented length limit.

### Error codes

Match errors by their machine-readable code, not their human-readable message. A
new code is backward compatible when it represents a new failure condition;
changing the HTTP status or code for an existing condition is breaking. Preserve
and surface an unfamiliar code so that you can add specific handling without
losing the original failure detail.

### Webhook events

After verifying a webhook signature, record or surface an unsupported event type
for follow-up, then acknowledge it with a `2xx` response. This prevents retries
that can't succeed while preserving the event for later handling. Don't process
the event as a known type. Continue to reject webhooks when
[signature verification](/api-reference/verify-webhook-signatures) fails.