Quickstart: Accept x402 payments with Facilitator Service

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+
Installed viem
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

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.

sign-authorization.ts

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

sign-proof.ts

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

body.json

{
  "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:

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 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:

{
  "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:

{
  "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 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:

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:

{
  "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.

Circle CLI

Agent marketplace

x402 facilitators

Quickstart: Accept x402 payments with Facilitator Service

Prerequisites

Step 1: Get a signed payment authorization from the buyer

Step 2: Build the seller proof

Step 3: Submit the payment

Step 4: Read the settlement response

Step 5: Confirm the payment settled

​Prerequisites

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

​Step 2: Build the seller proof

​Step 3: Submit the payment

​Step 4: Read the settlement response

​Step 5: Confirm the payment settled

Prerequisites

Step 1: Get a signed payment authorization from the buyer

Step 2: Build the seller proof

Step 3: Submit the payment

Step 4: Read the settlement response

Step 5: Confirm the payment settled