Settle an x402 payment

Settles an x402 payment. Facilitator Service validates the buyer’s EIP-3009 authorization, screens both parties, records the payment, and submits the USDC transfer through a Circle relayer.

Returns a terminal result (HTTP 200) if settlement resolves within the HTTP wait window. Returns HTTP 202 with a paymentId when settlement is still in flight at the wait deadline. See Get payment status to poll a pending payment.

Include a payment-identifier extension in the request body for idempotency scoped to your seller account. Retries with the same identifier converge on the same payment. Without an identifier, a retry must reuse the exact same signed buyer authorization or the retry is treated as a new charge.

POST /v1/facilitator/x402/settle

Settle an x402 payment

cURL

curl --request POST \
  --url https://api.circle.com/v1/facilitator/x402/settle \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "x402Version": 2,
  "paymentPayload": {
    "x402Version": 2,
    "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..."
      }
    },
    "resource": {
      "url": "https://api.example.com/premium",
      "description": "Premium report",
      "mimeType": "application/json"
    },
    "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",
      "assetTransferMethod": "eip3009"
    }
  }
}
'

200

{
  "success": true,
  "payer": "0x9aE2...",
  "transaction": "0x6f9e1d...",
  "network": "eip155:5042002",
  "amount": "1000000",
  "errorReason": "invalid_exact_evm_payload_signature",
  "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"
    }
  }
}

Authorizations

CircleApiKeyFacilitatorSellerProof

Authorization · string · header · required

Bearer token authentication with a Circle API key. Use this for production settlement after claiming your Facilitator Service seller account.

Body

application/json

x402Version · enum<integer> · required

x402 protocol version. Facilitator Service supports version 2.

Available options: 2

paymentPayload · object · required

x402 v2 payment payload. Includes the payment terms the buyer accepted and the signed EIP-3009 authorization that authorizes the USDC transfer.

Show child attributes

paymentRequirements · object · required

Payment terms the seller advertises for an x402 resource. Facilitator Service validates that the buyer's authorization matches these requirements.

Show child attributes

Response

200

application/json

Terminal settlement result

success · boolean · required

Whether the transfer settled onchain within the wait window. Check the settlement-status extension to distinguish failed from pending.

Example:

true

payer · string · required

Buyer address recovered from the signed authorization.

Example:

"0x9aE2..."

transaction · string · required

Transaction hash on terminal success. Empty string when settlement is still pending or failed before submission.

Example:

"0x6f9e1d..."

network · string · required

CAIP-2 network identifier for the settled payment.

Example:

"eip155:5042002"

amount · string

Amount in atomic USDC units.

Example:

"1000000"

errorReason · enum<string>

Terminal failure code. Present when success is false and the payment reached a terminal failed state. Omitted on pending responses.

Available options: invalid_x402_version, unsupported_scheme, invalid_network, invalid_payment_requirements, invalid_payload, invalid_exact_evm_payload_recipient_mismatch, invalid_exact_evm_payload_authorization_value_mismatch, invalid_exact_evm_payload_authorization_valid_after, invalid_exact_evm_payload_authorization_valid_before, invalid_exact_evm_payload_signature, invalid_transaction_state, insufficient_funds

Example:

"invalid_exact_evm_payload_signature"

extensions · object

x402 extensions. On pending responses, Facilitator Service returns a settlement-status extension with paymentId, statusUrl, retryAfterMs, and expiresAt.

Example:

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