Facilitator course
Facilitator Track: Settlement Basics for x402
A facilitator can simplify blockchain verification and settlement, but it does not remove the seller's responsibility for route behavior, logging, and payment safety.
What the facilitator does
In x402, a facilitator is an optional service that helps a resource server verify payment payloads and settle transactions. The server can verify and settle directly, but a facilitator reduces blockchain-specific operational work for sellers that want to focus on HTTP resources.
"The facilitator is an optional but recommended service."
The facilitator is not a reason to skip seller checks. The seller still owns the route contract, price configuration, paid response, error behavior, logs, and user-facing promises. A facilitator can say whether a payment payload is valid and can submit settlement; it cannot tell you whether your API should have been priced, available, or allowed for this buyer.
Verification and settlement are different
Verification asks whether the signed payment payload satisfies the seller's declared payment requirements. Settlement executes the transaction on the target network. Keep those as two separate events in code, logs, dashboards, and incident notes.
1. Seller receives a paid retry with a signed PaymentPayload.
2. Seller asks the facilitator to verify the payload against PaymentRequirements.
3. Seller serves the resource only if verification is valid.
4. Seller asks the facilitator to settle, or settles directly.
5. Facilitator submits the transaction and returns the settlement result.
6. Seller returns the resource and payment response metadata to the client.The official docs also note that x402 uses CAIP-2 network identifiers. That matters for facilitators because verification and settlement logic depends on the selected scheme and network. A seller that accepts multiple networks must log which requirement the buyer chose.
Design for failure before traffic arrives
Facilitator integration creates new failure modes: the facilitator endpoint can be unreachable, verification can fail, settlement can fail after successful verification, or a client can retry the same logical payment. Each case should have a clear HTTP response and log event.
Duplicate settlement deserves special attention. The x402 docs describe a Solana settlement cache in mechanism packages and the payment-identifier extension for idempotent retries. The implementation choice depends on your scheme and stack, but the product requirement is simple: retries should not accidentally process the same logical payment twice.
Operate it like payment infrastructure
A practical facilitator integration has boring logs. Every paid request should make it possible to answer: what route was requested, what requirement was selected, what payment ID was used, what facilitator handled verification, what settlement status came back, and whether the paid resource was served.
route=/weather
scheme=exact
network=eip155:84532
price=$0.001
payment_id=pay_...
verify_status=valid
settle_status=settled
facilitator_url=https://x402.org/facilitatorIf a facilitator is down, the seller can either fail closed or use another configured facilitator. Do not silently serve paid content for free unless that is an explicit product policy. Do not silently charge without returning content. Document the failure policy before exposing the route to agents.
Sources used
- x402 docs: Facilitator
Defines facilitator responsibilities for payment verification and settlement.
- x402 docs: HTTP 402
Explains how x402 uses HTTP 402 to communicate payment requirements.
- x402 docs: Client / Server
Summarizes client and server responsibilities in x402.
- x402 docs: Networks and Token Support
Documents CAIP-2 network identifiers and supported network namespaces.
- x402 docs: Payment-Identifier extension
Documents idempotency support for retries without duplicate payment processing.
- x402 Foundation GitHub repository
Open-source SDKs, examples, and the typical x402 request/payment/settlement flow.