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

# 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/agent-stack/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.

<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).
</Note>

```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/agent-stack/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": "1781308800",
        "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

[`/settle`](/api-reference/agent-stack/facilitator-service/settle-payment)
returns one of two shapes. 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.** Facilitator Service responds with a `paymentId` you poll on
[`/status`](/api-reference/agent-stack/facilitator-service/get-payment-status):

```json theme={null}
{
  "success": false,
  "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",
      "retryAfterMs": 1000,
      "expiresAt": "2026-06-11T22:31:07Z"
    }
  }
}
```

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

## Step 5: Confirm the payment settled

Sign a fresh seller proof for the
[`/status`](/api-reference/agent-stack/facilitator-service/get-payment-status)
call with `purpose: "status"`, then poll at the interval indicated by
`retryAfterMs` until the payment reaches `completed` or `failed`.

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.