> ## 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. # Quickstart: Accept x402 payments with Facilitator Service > Accept your first x402 payment on Arc testnet with the Facilitator Service keyless trial Accept a signed x402 payment authorization from a buyer, submit it to Facilitator Service on Arc testnet, and confirm that USDC settled to your seller address. This quickstart uses the keyless trial, so no Circle account or API key is required. ## Prerequisites Before you begin, ensure that you've: * Installed [Node.js v22.6+](https://nodejs.org/) * Installed [viem](https://viem.sh/) * Created an EVM wallet, which will be your `payTo` address for receiving USDC payments * Obtained the private key controlling `payTo`, which will be used to sign the seller proof * Funded a buyer wallet with Arc testnet USDC from the [Circle Faucet](https://faucet.circle.com) ## Step 1: Get a signed payment authorization from the buyer In production, the buyer's wallet or agent signs the EIP-3009 authorization and sends it to your API in the x402 request. For this quickstart, sign one from a test wallet you control so you can act as both buyer and seller. The authorization signs against the USDC contract on Arc testnet. ```typescript sign-authorization.ts theme={null} import { privateKeyToAccount } from "viem/accounts"; import { toHex } from "viem"; const buyer = privateKeyToAccount( process.env.BUYER_PRIVATE_KEY as `0x${string}`, ); const payTo = "0x7c3eA945Fc4253255D8260fC18C2deE3D8c5DD3a"; const nonce = crypto.getRandomValues(new Uint8Array(32)); const validBefore = BigInt(Math.floor(Date.now() / 1000) + 3600); const signature = await buyer.signTypedData({ domain: { name: "USDC", version: "2", chainId: 5042002, verifyingContract: "0x3600000000000000000000000000000000000000", }, types: { TransferWithAuthorization: [ { name: "from", type: "address" }, { name: "to", type: "address" }, { name: "value", type: "uint256" }, { name: "validAfter", type: "uint256" }, { name: "validBefore", type: "uint256" }, { name: "nonce", type: "bytes32" }, ], }, primaryType: "TransferWithAuthorization", message: { from: buyer.address, to: payTo, value: 1000000n, // 1 USDC (6 decimals) validAfter: 0n, validBefore, nonce: toHex(nonce), }, }); ``` Keep the signature and message fields. You pass them to [`/settle`](/api-reference/facilitator-service/settle-payment) in Step 3 as `payload.signature` and `payload.authorization`. ## Step 2: Build the seller proof The seller proof is a base64url-encoded envelope carrying an EIP-712 signature. It proves you control `payTo` and binds the request to the `purpose` and body being sent. Sign each Facilitator Service call with a proof whose `purpose` matches the route (`verify`, `settle`, or `status`). For a step-by-step walkthrough and the full signing rules, see [Sign a seller proof](/facilitator-service/sign-seller-proof). ```typescript sign-proof.ts theme={null} import { privateKeyToAccount } from "viem/accounts"; import { keccak256, toBytes } from "viem"; const account = privateKeyToAccount( process.env.SELLER_PRIVATE_KEY as `0x${string}`, ); const network = "eip155:5042002"; // Arc testnet const payTo = "0x7c3eA945Fc4253255D8260fC18C2deE3D8c5DD3a"; async function buildProof( purpose: "verify" | "settle" | "status", method: string, body: string, ) { const nonce = crypto.getRandomValues(new Uint8Array(32)); const issuedAt = Math.floor(Date.now() / 1000); const expiresAt = issuedAt + 300; // 5 minutes const signature = await account.signTypedData({ domain: { name: "Circle Facilitator Seller Request", version: "1", chainId: 5042002, }, types: { SellerRequest: [ { name: "purpose", type: "string" }, { name: "method", type: "string" }, { name: "bodyHash", type: "bytes32" }, { name: "network", type: "string" }, { name: "payTo", type: "address" }, { name: "nonce", type: "bytes32" }, { name: "issuedAt", type: "uint64" }, { name: "expiresAt", type: "uint64" }, ], }, primaryType: "SellerRequest", message: { purpose, method: method.toUpperCase(), bodyHash: keccak256(toBytes(body)), network, payTo, nonce: `0x${Buffer.from(nonce).toString("hex")}`, issuedAt: BigInt(issuedAt), expiresAt: BigInt(expiresAt), }, }); const envelope = { version: 1, signature, network, payTo, nonce: `0x${Buffer.from(nonce).toString("hex")}`, issuedAt, expiresAt, }; return Buffer.from(JSON.stringify(envelope)).toString("base64url"); } ``` ## Step 3: Submit the payment [`/settle`](/api-reference/facilitator-service/settle-payment) is the authoritative money path. It validates the authorization, screens buyer and seller, records durable payment state, submits the USDC transfer, and returns terminal evidence or a pending response. You can include a `payment-identifier` extension in the request body for idempotency scoped to your seller account. When supplied, its `id` must be 16 to 128 characters from `[A-Za-z0-9_-]`. When omitted, the facilitator uses an internal surrogate. In that case, a retry must reuse the exact same signed authorization, because a fresh authorization without an identifier is treated as a new charge. ```json body.json theme={null} { "x402Version": 2, "paymentPayload": { "x402Version": 2, "resource": { "url": "https://api.example.com/premium", "description": "Premium report", "mimeType": "application/json" }, "accepted": { "scheme": "exact", "network": "eip155:5042002", "amount": "1000000", "asset": "0x3600000000000000000000000000000000000000", "payTo": "0x7c3eA945Fc4253255D8260fC18C2deE3D8c5DD3a", "maxTimeoutSeconds": 12, "extra": { "name": "USDC", "version": "2", "assetTransferMethod": "eip3009" } }, "payload": { "signature": "0x...", "authorization": { "from": "0x9aE2...", "to": "0x7c3eA945Fc4253255D8260fC18C2deE3D8c5DD3a", "value": "1000000", "validAfter": "0", "validBefore": "2208988800", "nonce": "0x4d3f..." } }, "extensions": { "payment-identifier": { "info": { "required": true, "id": "pay_5f0d3c1a9b7e4d2c" } } } }, "paymentRequirements": { "scheme": "exact", "network": "eip155:5042002", "amount": "1000000", "asset": "0x3600000000000000000000000000000000000000", "payTo": "0x7c3eA945Fc4253255D8260fC18C2deE3D8c5DD3a", "maxTimeoutSeconds": 12, "extra": { "name": "USDC", "version": "2" } } } ``` Generate a fresh proof for this call using the `sign-proof.ts` script from Step 2, then pass it in the `Facilitator-Seller-Proof` header: ```bash theme={null} PROOF="" curl -X POST https://api.circle.com/v1/facilitator/x402/settle \ -H "Facilitator-Seller-Proof: $PROOF" \ -H "Content-Type: application/json" \ -d @body.json ``` ## Step 4: Read the settlement response A settlement outcome from [`/settle`](/api-reference/facilitator-service/settle-payment) always uses HTTP 200 and takes one of two shapes. A rejected request or an internal failure uses the documented 4xx or 5xx response instead and carries no settlement outcome. Terminal success means the transfer confirmed in the HTTP wait window. Facilitator Service responds with: ```json theme={null} { "success": true, "payer": "0x9aE2...", "transaction": "0x6f9e1d...", "network": "eip155:5042002", "amount": "1000000" } ``` Pending means confirmation did not arrive in time. **Do not fulfill on pending.** The response is still HTTP 200, with `success: false` and `errorReason: settlement_pending`. Use the `paymentId` to reconcile the outcome through [`/status`](/api-reference/facilitator-service/get-payment-status): ```json theme={null} { "success": false, "errorReason": "settlement_pending", "payer": "0x9aE2...", "transaction": "", "network": "eip155:5042002", "extensions": { "settlement-status": { "status": "pending", "paymentId": "5b3f6c1e-9d2a-4f08-b1c7-2e9a14d0c3aa", "statusUrl": "https://api.circle.com/v1/facilitator/x402/status/5b3f6c1e-9d2a-4f08-b1c7-2e9a14d0c3aa" } } } ``` `transaction` is empty on a pending response: Facilitator Service records a transaction hash only once terminal evidence arrives. A timeout is not evidence of failure. To retry a pending payment, reuse the same `payment-identifier` you supplied on the first call. If you did not supply one, retry with the exact same signed buyer authorization. Never re-sign, or you risk charging the buyer twice. ## Step 5: Confirm the payment settled Sign a fresh seller proof for the [`/status`](/api-reference/facilitator-service/get-payment-status) call with `purpose: "status"`, then read the payment until it reaches `completed` or `failed`. Settlement returns no retry interval, so choose your own reconcile cadence. Substitute the base64url proof from `sign-proof.ts`: ```bash theme={null} PROOF="" curl https://api.circle.com/v1/facilitator/x402/status/5b3f6c1e-9d2a-4f08-b1c7-2e9a14d0c3aa \ -H "Facilitator-Seller-Proof: $PROOF" ``` Facilitator Service responds with `completed` once the USDC transfer settled to `payTo`: ```json theme={null} { "paymentId": "5b3f6c1e-9d2a-4f08-b1c7-2e9a14d0c3aa", "status": "completed", "reason": null, "transaction": "0x6f9e1d...", "network": "eip155:5042002", "amount": "1000000", "payer": "0x9aE2...", "updatedAt": "2026-06-11T22:30:11Z" } ``` You've settled a payment through Facilitator Service. In a real x402 integration, this is when your API responds to the buyer with the paid resource.