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

# What is x402?

> The x402 open payment standard and how Circle's facilitators use it to settle USDC payments for HTTP resources

x402 is an open, neutral standard for internet-native payments built on the HTTP
`402 Payment Required` status code. It defines how a server communicates that
payment is required to access a resource, and how a client can provide proof of
payment. x402 is not a payment system itself. It is a negotiation protocol,
agnostic to how payments are constructed, verified, or settled.

Circle operates two x402 facilitators.
[Facilitator Service](/facilitator-service) settles USDC onchain on every
payment through a Circle relayer. [Gateway Nanopayments](/gateway-nanopayments)
batches signed authorizations into aggregated settlement to make sub-cent
payments economically viable. Both plug into the same x402 flow.

For the full protocol spec, see [x402.org](https://www.x402.org/) and the
[x402 documentation](https://docs.x402.org/). The reference implementation lives
in the [x402 GitHub repository](https://github.com/coinbase/x402).

## The problem with internet payments

Traditional payment systems were not designed for programmatic, high-frequency
transactions. Credit cards carry high fixed fees, require account creation, and
involve slow settlement. Standard onchain payments require gas for every
transaction, making sub-cent payments uneconomical. Neither approach works well
for AI agents, per-request billing, or machine-to-machine commerce.

x402 addresses this by making payment negotiation a native part of HTTP. A
server declares that payment is required, a client provides a payment payload,
and the exchange happens in a single request-response cycle. The actual payment
method is flexible. Any scheme that can produce a verifiable payment payload can
work with x402.

## How x402 works

The x402 protocol uses three HTTP headers to negotiate payment between a client
and a server:

| Header | Direction | Purpose |
| - | - | - |
| `PAYMENT-REQUIRED` | Server to client | Payment requirements (accepted schemes, price, network, destination) |
| `PAYMENT-SIGNATURE` | Client to server | Signed payment payload proving the client has authorized payment |
| `PAYMENT-RESPONSE` | Server to client | Confirmation that the payment was verified, returned with the resource |

The typical flow is:

```mermaid theme={null}
sequenceDiagram
    participant Client as Client (Buyer)
    participant Server as Server (Seller)

    Client->>Server: 1. GET /resource
    Server-->>Client: 2. 402 Payment Required + PAYMENT-REQUIRED header

    Note left of Client: Signs payment payload

    Client->>Server: 3. GET /resource + PAYMENT-SIGNATURE header

    Note right of Server: Verifies payment

    Server-->>Client: 4. 200 OK + resource + PAYMENT-RESPONSE header
```

1. The client requests a paid resource.
2. The server responds with `402 Payment Required`, including payment details
   such as the accepted payment schemes, price, network, and destination
   address.
3. The client selects a payment option, constructs and signs a payment payload,
   and retries the request with the `PAYMENT-SIGNATURE` header.
4. The server verifies the payment (directly or through a facilitator) and
   returns the resource along with a confirmation in the `PAYMENT-RESPONSE`
   header.

x402 defines this negotiation flow. How the payment payload is constructed, how
it is verified, and how funds ultimately move are determined by the payment
method and facilitator, not by x402 itself.

## Core concepts

### Buyers and sellers

* **Buyer (client)**: The entity requesting a paid resource. This can be a
  human-operated application, an AI agent, or any programmatic HTTP client.
  Buyers construct payment payloads using whatever payment method the server
  accepts.
* **Seller (server)**: The resource provider that requires payment. Sellers
  declare their accepted payment methods in the `402` response, verify incoming
  payment payloads, and serve the resource when payment is valid. Any
  HTTP-accessible API or service can act as a seller.

### Facilitators

A facilitator is an optional service that handles payment verification and
settlement on behalf of sellers. By using a facilitator, sellers avoid needing
to verify payment payloads or interact with blockchain infrastructure
themselves.

Different facilitators can support different payment methods. A seller connects
to a facilitator and automatically gains access to the payment methods that
facilitator supports. Circle operates two:
[Facilitator Service](/facilitator-service) and
[Gateway Nanopayments](/gateway-nanopayments).

### Payment schemes

x402 supports multiple payment schemes. A payment scheme defines how payment
payloads are constructed, signed, and verified. The `402` response from a server
lists the schemes it accepts, and the client picks one it can fulfill.

Both Circle facilitators use the `exact` scheme with EIP-3009
`TransferWithAuthorization` signatures. They sign against different EIP-712
domains because they use different settlement models.

## How Facilitator Service fits in

[Facilitator Service](/facilitator-service) settles each x402 payment onchain
through a Circle relayer:

* Buyers sign an EIP-3009 `TransferWithAuthorization` against the USDC contract
  on Arc, Base, or Polygon PoS.
* The seller passes the signed authorization to Facilitator Service.
* Facilitator Service verifies the signature, screens both parties, and submits
  the USDC transfer onchain. Circle pays the settlement gas.

Facilitator Service is the right choice when you want the simplest hosted x402
experience with onchain settlement on every payment, and don't need sub-cent
payment economics.

## How Gateway Nanopayments fits in

[Gateway Nanopayments](/gateway-nanopayments) uses Circle Gateway's
[batched settlement](/gateway-nanopayments/concepts/batched-settlement)
infrastructure to make sub-cent payments economically viable:

* Buyers fund their payments from a Gateway Wallet balance (deposited once
  onchain).
* When a server requests payment through a `402` response, the buyer signs an
  offchain EIP-3009 authorization against the `GatewayWalletBatched` domain
  (zero gas) and includes it in the `PAYMENT-SIGNATURE` header.
* The server or its facilitator submits the authorization to Gateway for
  verification and settlement.
* Gateway collects authorizations and settles net positions in bulk onchain,
  paying gas once per batch instead of once per payment.

From x402's perspective, Gateway Nanopayments is just another payment method.
Clients and servers use the same `402` negotiation flow. The difference is that
the underlying payment is gasless and settled through batching, which is what
makes sub-cent payments economically viable.