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

Facilitator Service supports two
[payment schemes](/facilitator-service/how-it-works.md#payment-schemes): `exact`
for fixed prices and `upto` for usage-based prices.

**exact scheme**

Accept a fixed-amount payment with the `exact` scheme.

## Prerequisites

Before you begin, ensure that you've:

* Installed [Node.js v22.18+](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/all/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.

> [!NOTE]
>
> 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.md).

```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/all/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="<base64url proof from sign-proof.ts>"

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

> [!WARNING]
>
> 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/all/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="<base64url proof from sign-proof.ts>"

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.

**upto scheme**

Accept a usage-based payment with the `upto` scheme.

## Prerequisites

Before you begin, ensure that you've:

* Installed [Node.js v22.6+](https://nodejs.org/)
* Installed [viem](https://viem.sh/)
* Obtained a Circle [API key](/api-reference/keys.md#api-keys)
* 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)
* [Set up a Permit2 allowance](/facilitator-service/set-up-permit2-allowance.md) on
  the buyer's USDC

## Step 1: Get a signed payment authorization from the buyer

In production, the buyer's wallet or agent signs the Permit2 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 Permit2 contract and binds to the Circle
facilitator wallet at `extra.facilitatorAddress`. Copy that address from the
`upto` kind in
[`/supported`](/api-reference/facilitator-service/all/get-supported). Circle
rotates facilitator wallets, so hardcoding breaks.

```typescript sign-upto-authorization.ts theme={null}
import { privateKeyToAccount } from "viem/accounts";

const buyer = privateKeyToAccount(
  process.env.BUYER_PRIVATE_KEY as `0x${string}`,
);
const now: bigint = BigInt(Math.floor(Date.now() / 1000));
const nonce: bigint = BigInt(
  `0x${Buffer.from(crypto.getRandomValues(new Uint8Array(32))).toString("hex")}`,
);

const message = {
  permitted: {
    token: "0x3600000000000000000000000000000000000000",
    amount: 5000000n, // 5 USDC maximum (6 decimals)
  },
  spender: "0x4020A4f3b7b90ccA423B9fabCc0CE57C6C240002",
  nonce,
  deadline: now + 900n,
  witness: {
    to: "0x7c3ea945Fc4253255d8260fc18c2dee3D8C5dD3A", // payTo
    facilitator: "0x2240278661b83f55D31B2506F77266f6fFd21D55", // extra.facilitatorAddress
    validAfter: now - 60n,
  },
} as const;

const signature: `0x${string}` = await buyer.signTypedData({
  domain: {
    name: "Permit2",
    chainId: 5042002,
    verifyingContract: "0x000000000022D473030F116dDEE9F6B43aC78BA3",
  },
  types: {
    PermitWitnessTransferFrom: [
      { name: "permitted", type: "TokenPermissions" },
      { name: "spender", type: "address" },
      { name: "nonce", type: "uint256" },
      { name: "deadline", type: "uint256" },
      { name: "witness", type: "Witness" },
    ],
    TokenPermissions: [
      { name: "token", type: "address" },
      { name: "amount", type: "uint256" },
    ],
    Witness: [
      { name: "to", type: "address" },
      { name: "facilitator", type: "address" },
      { name: "validAfter", type: "uint256" },
    ],
  },
  primaryType: "PermitWitnessTransferFrom",
  message,
});
```

> [!NOTE]
>
> The authorization is rejected if `witness.validAfter` is still in the future or
> `deadline` is less than 10 seconds away. After `deadline` passes, `/settle`
> returns
> [`HTTP 403 authorization_expired`](/api-reference/facilitator-service/errors#http-status-errors).

Keep the signature and message fields. You pass them to `/verify` and `/settle`
in Step 3 as `payload.signature` and `payload.permit2Authorization`.

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

> [!NOTE]
>
> 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.md).

```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: Verify the authorization

Call `/verify` with the signed maximum to confirm the authorization is valid
before you serve the request.

### Step 3.1. Build the verification request

Build `verify-body.json` with your payment requirements, the signature from Step
1, and the matching `permit2Authorization`. `accepted.amount` and
`paymentRequirements.amount` both carry the signed maximum (5 USDC in the
example):

```json verify-body.json theme={null}
{
  "x402Version": 2,
  "paymentPayload": {
    "x402Version": 2,
    "resource": {
      "url": "https://api.example.com/llm/completions",
      "description": "Metered LLM completion",
      "mimeType": "application/json"
    },
    "accepted": {
      "scheme": "upto",
      "network": "eip155:5042002",
      "amount": "5000000",
      "asset": "0x3600000000000000000000000000000000000000",
      "payTo": "0x7c3ea945Fc4253255d8260fc18c2dee3D8C5dD3A",
      "maxTimeoutSeconds": 300,
      "extra": {
        "name": "USDC",
        "version": "2",
        "assetTransferMethod": "permit2",
        "facilitatorAddress": "0x2240278661b83f55D31B2506F77266f6fFd21D55"
      }
    },
    "payload": {
      "signature": "0x...",
      "permit2Authorization": {
        "from": "0x9aE2...",
        "permitted": {
          "token": "0x3600000000000000000000000000000000000000",
          "amount": "5000000"
        },
        "spender": "0x4020A4f3b7b90ccA423B9fabCc0CE57C6C240002",
        "nonce": "1791399400123456",
        "deadline": "1791400300",
        "witness": {
          "to": "0x7c3ea945Fc4253255d8260fc18c2dee3D8C5dD3A",
          "facilitator": "0x2240278661b83f55D31B2506F77266f6fFd21D55",
          "validAfter": "1791399400"
        }
      }
    },
    "extensions": {
      "payment-identifier": {
        "info": { "required": true, "id": "pay_5f0d3c1a9b7e4d2c" }
      }
    }
  },
  "paymentRequirements": {
    "scheme": "upto",
    "network": "eip155:5042002",
    "amount": "5000000",
    "asset": "0x3600000000000000000000000000000000000000",
    "payTo": "0x7c3ea945Fc4253255d8260fc18c2dee3D8C5dD3A",
    "maxTimeoutSeconds": 300,
    "extra": {
      "name": "USDC",
      "version": "2",
      "assetTransferMethod": "permit2",
      "facilitatorAddress": "0x2240278661b83f55D31B2506F77266f6fFd21D55"
    }
  }
}
```

#### (Conditional) Add the gasless permit extension

If the buyer used a gasless EIP-2612 permit instead of an onchain Permit2
approval, attach it under `paymentPayload.extensions.eip2612GasSponsoring`:

```json theme={null}
{
  "eip2612GasSponsoring": {
    "info": {
      "from": "0x9aE2...",
      "asset": "0x3600000000000000000000000000000000000000",
      "spender": "0x000000000022D473030F116dDEE9F6B43aC78BA3",
      "amount": "5000000",
      "nonce": "0",
      "deadline": "1791400300",
      "signature": "0x30d1893d...",
      "version": "1"
    }
  }
}
```

Copy the following from the buyer's signed permit:

* `from` must equal `permit2Authorization.from`.
* `asset` must equal the signed `permitted.token`.
* `spender` must be Permit2 (`0x000000000022D473030F116dDEE9F6B43aC78BA3`).
* `amount` must equal the signed Permit2 maximum, `permitted.amount`.
* `nonce` is the buyer's current USDC `nonces(owner)` value.
* `deadline` must be at least 10 seconds in the future.
* `signature` is a 65-byte signature, as hex.

### Step 3.2. Submit the verification

Call `/verify` with `verify-body.json` and a fresh seller proof signed with
`purpose: "verify"`:

```bash theme={null}
PROOF="<base64url proof from sign-proof.ts>"

curl -X POST https://api.circle.com/v1/facilitator/x402/verify \
  -H "Authorization: Bearer $CIRCLE_API_KEY" \
  -H "Facilitator-Seller-Proof: $PROOF" \
  -H "Content-Type: application/json" \
  -d @verify-body.json
```

## Step 4: Settle the actual amount

When `isValid: true` comes back, serve the request and measure usage. Then
settle for the actual charge.

### Step 4.1. Build the settlement request

Build `settle-body.json` from `verify-body.json` by changing only
`paymentRequirements.amount` to the actual charge. This example charges 1.234567
USDC of the 5 USDC maximum:

```json settle-body.json theme={null}
{
  "x402Version": 2,
  "paymentPayload": { "...": "identical to verify-body.json" },
  "paymentRequirements": {
    "scheme": "upto",
    "network": "eip155:5042002",
    "amount": "1234567",
    "asset": "0x3600000000000000000000000000000000000000",
    "payTo": "0x7c3ea945Fc4253255d8260fc18c2dee3D8C5dD3A",
    "maxTimeoutSeconds": 300,
    "extra": {
      "name": "USDC",
      "version": "2",
      "assetTransferMethod": "permit2",
      "facilitatorAddress": "0x2240278661b83f55D31B2506F77266f6fFd21D55"
    }
  }
}
```

### Step 4.2. Submit the settlement

Call `/settle` with `settle-body.json` and a fresh seller proof signed with
`purpose: "settle"`:

```bash theme={null}
PROOF="<base64url proof from sign-proof.ts, purpose=settle>"

curl -X POST https://api.circle.com/v1/facilitator/x402/settle \
  -H "Authorization: Bearer $CIRCLE_API_KEY" \
  -H "Facilitator-Seller-Proof: $PROOF" \
  -H "Content-Type: application/json" \
  -d @settle-body.json
```

> [!NOTE]
>
> If the actual charge exceeds the signed maximum, `/settle` returns
> `invalid_upto_evm_payload_settlement_exceeds_amount`. If the request used
> nothing, settle with `paymentRequirements.amount` set to `"0"` and the payment
> completes without an onchain transaction. For the full behavior reference, see
> the [`/settle` endpoint](/api-reference/facilitator-service/all/settle-payment).

## Step 5: Read the settlement response

A settlement outcome from
[`/settle`](/api-reference/facilitator-service/all/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": "1234567"
}
```

Once Facilitator Service records the payment, it returns `payer` in lowercase. A
`0` settlement returns `success: true` with an empty `transaction` and
`amount: "0"`. No USDC moves.

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/all/get-payment-status).

> [!WARNING]
>
> A timeout is not evidence of failure. To retry a pending payment, reuse the same
> `payment-identifier` you supplied on the first call, or the same signed
> authorization. Facilitator Service settles each `upto` authorization at most
> once per Circle account, so a retry always converges on the original payment
> rather than charging twice. Never re-sign.

## Step 6: Confirm the payment settled

Sign a fresh seller proof for the
[`/status`](/api-reference/facilitator-service/all/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.

```bash theme={null}
PROOF="<base64url proof from sign-proof.ts>"

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": "1234567",
  "payer": "0x9aE2...",
  "updatedAt": "2026-06-11T22:30:11Z"
}
```

A `0` settlement reports `transaction: null`.

You've settled a usage-based payment through Facilitator Service. In a real x402
integration, this is when your API responds to the buyer with the paid resource.