Your agent reaches a paid service during an outage. The service is alive, the client has signed a payment authorization, and the facilitator endpoint does not answer.
Should the service run the job anyway? Should it try a second facilitator? Could the first request have settled even though the response was lost?
Those are the real questions behind a facilitator, a payment service in x402, an HTTP payment protocol. The facilitator moves payment verification and settlement calls out of the resource server, but it also becomes a dependency in the payment decision. When its answer is unknown, the resource server should pause execution, preserve the payment reference, and reconcile settlement state before retrying.
Choose who owns payment state
An x402 facilitator is a payment service that verifies a client’s payment authorization and can submit or complete settlement on the network. It is not the AI runtime, not the service provider running Tangle jobs, and not an evaluator of the job result.
Use a hosted facilitator when you want a provider endpoint without operating payment verification, settlement, or chain infrastructure. Self-host when you need control over availability, data handling, and deployment. Use local verification and settlement when the network and token scheme make it practical and your team can operate the chain integration.
In all three models, an unknown payment state must not be treated as approval. After settlement, the service owes the client a durable job outcome or a documented recovery path.
Name the actors before the outage
x402 is an open Hypertext Transfer Protocol (HTTP) payment protocol. The client is the agent or application that wants a resource. The resource server is the service that owns the endpoint and decides whether to admit work. The facilitator is the optional payment utility that verifies and settles on the resource server’s behalf.
A Blueprint is a public Tangle service definition with named jobs, operator rules, and an execution lifecycle. An operator supplies the machine and runs a Blueprint service instance.
A runtime is the process that executes a job. A job router maps a job type to its handler.
An agent profile is the client-side policy for accepted networks, tokens, recipients, budgets, timeouts, and retries. A trace is the record joining the HTTP request, payment decision, job, runtime attempt, and result.
A service-level agreement (SLA) is a provider’s stated availability or response commitment, not a guarantee that the paid job will finish.
An evaluation is a check against an expected result condition. The facilitator can say that payment authorization satisfied payment rules; it cannot say that an AI summary was accurate.
What the facilitator does
The current x402 flow has a clear division of labor.
The x402 protocol repository describes the resource server returning PAYMENT-REQUIRED, the client retrying with PAYMENT-SIGNATURE, and the server returning PAYMENT-RESPONSE after payment processing.
With a facilitator, the resource server usually makes two calls:
resource server -> facilitator /verify
resource server -> facilitator /settleVerification asks whether the authorization is valid for the requested scheme, network, asset, amount, recipient, and current state. Settlement asks the facilitator to submit or complete the transfer and return a result.
The facilitator does not normally need the job’s private input, model output, or business logic. The resource server should send only payment metadata and the authorization required by the scheme.
The x402 facilitator documentation and Coinbase facilitator documentation describe these roles from the protocol and provider perspectives. The provider’s current terms and supported networks remain the authority for a specific deployment.
A Blueprint payment path
For a paid Blueprint job, the boundary can look like this:
agent profile
|
| POST /jobs
v
resource server / x402 gateway
| \
| \-- /verify --> facilitator
| \-- /settle --> facilitator --> network
|
| settled payment
v
Blueprint runner -> job router -> runtime -> resultThe gateway is the admission point. The runner is the job lifecycle. The job router is the handler dispatch. The facilitator is a payment dependency between the gateway and the network.
The public Tangle x402 gateway pairs gateway behavior with a Blueprint producer so a verified payment can become a runnable job. It also exposes a settle-before-execution path. That ordering is important because expensive execution should not begin merely because a client sent a plausible signature.
It creates a corresponding obligation. If settlement succeeds and the runtime crashes, the resource server must recover the job or record a failure with the payment reference.
Choose a facilitator operating model
Hosted facilitator
A hosted facilitator gives a team a URL and a supported integration. It avoids operating payment-verification, settlement, and chain infrastructure during the initial deployment. It can support several networks when the provider already exposes every network, asset, and payment scheme the service accepts.
The tradeoff is dependency concentration. The provider can have an outage, change limits, retire a scheme, change pricing, restrict regions, or expose metadata to its operators according to its policy. The service also depends on the provider’s latency and incident response.
Hosted does not mean untrusted by definition. It means you are accepting a provider boundary instead of operating that boundary yourself.
Self-hosted facilitator
Self-hosting moves the facilitator process into infrastructure your team controls. That keeps its logs, releases, network calls, and deployment schedule inside systems your team operates. It does not remove the need for chain nodes, signing policy, upgrades, monitoring, or network-specific correctness.
Self-hosting is valuable when the facilitator is on the critical path for high-volume or high-value service requests. It is a poor choice if nobody owns its keys, upgrades, and incident response.
Local verification and settlement
Some payment schemes allow the resource server to verify and settle directly. Direct settlement removes the facilitator network hop; measure verification and settlement latency before setting the service timeout. It also makes the resource server responsible for chain interaction, token semantics, nonce or authorization handling, gas, reorg behavior, and upgrade compatibility.
The x402 project describes production options including a supported production facilitator, a self-hosted facilitator, and local verification and settlement where appropriate. Read the current x402 production guidance and scheme documentation before choosing.
Compare facilitator boundaries
Ask what the facilitator can observe, change, delay, or deny.
| Risk | Hosted facilitator | Self-hosted facilitator | Local handling |
|---|---|---|---|
| Payment metadata visibility | Provider policy | Your infrastructure | Your infrastructure |
| Availability | Provider SLA and incidents | Your deployment and chain access | Your deployment and chain access |
| Scheme upgrades | Provider schedule | Your release process | Your release process |
| Key custody | Provider or scheme-specific model | Your key policy | Your key policy |
| Chain integration burden | Lower | Medium | Highest |
| Operational blast radius | Shared provider | Your fleet | Your service and chain stack |
The table is not a security score. It is a prompt to decide which boundary the business can own.
A facilitator should not be able to alter the client’s intended recipient or amount without the payment authorization failing. That is the trust-minimizing goal of the protocol. The resource server should still inspect the returned payment result and confirm it matches the request it admitted.
Availability has two different failures
Known failure means the facilitator answered that verification or settlement failed. The service can return a payment error and avoid execution.
Unknown state means the request timed out, the connection dropped, or the response was malformed. The service cannot infer whether the network accepted the transfer.
The safe state machine is:
payment received
|
+-- verification rejected --> no execution
|
+-- verification accepted -> settlement request
|
+-- settled --> admit one job
|
+-- rejected -> no execution
|
+-- unknown --> reconcile, do not executeIn the last branch, executing before reconciliation creates unpaid compute. Executing on an unknown result may create unpaid compute. Retrying settlement blindly may create a duplicate effect if the scheme is not idempotent. The facilitator and payment scheme must document how to query or safely retry status.
Fallback routing is not automatic
A second provider improves availability only after both providers support the same network, asset, scheme, authorization semantics, reconciliation process, and replay behavior.
Do not send the same authorization to two settlement endpoints when the first call timed out. First reconcile the original settlement or use the scheme’s documented idempotency and status mechanism.
A sensible fallback design chooses the facilitator before the payment is signed. The agent profile or resource server policy records which provider is allowed for that request. If the first provider is unavailable before any authorization is signed, choose the second provider and issue a fresh payment requirement. If a settlement attempt is already in flight, reconcile it instead of racing another settlement.
The tradeoff is operational complexity. You now need provider health, capability matching, route selection, and a way to explain which provider saw the authorization.
A small routing policy
The following is illustrative TypeScript pseudocode. It shows the control decisions without claiming to be a drop-in x402 software development kit (SDK) interface.
type PaymentState = 'unverified' | 'verified' | 'settled' | 'unknown' | 'rejected'
async function admitPaidJob(input: JobInput, payment: PaymentAuthorization) {
const provider = chooseProviderBeforeSigning(payment.network, payment.scheme)
const verification = await provider.verify(payment, input)
if (!verification.accepted) {
return { status: 'payment_rejected' as const }
}
const settlement = await provider.settle(payment)
if (settlement.status === 'unknown') {
return { status: 'reconcile_before_execution' as const }
}
if (settlement.status !== 'settled') {
return { status: 'payment_failed' as const }
}
return enqueueExactlyOnce({ input, payment, settlement })
}The important detail is not the type names.
The important detail is that only settled reaches enqueueExactlyOnce.
The actual x402 client and facilitator APIs should come from their current official documentation.
Data minimization is part of decentralization
Decentralizing the facilitator does not mean sending the same private payload to more services. Keep payment metadata and job data on separate paths.
The facilitator may need:
- Network and asset identifiers.
- Amount and recipient.
- The payment authorization.
- A request or resource identifier.
It should not need:
- A private document.
- Model weights.
- The full prompt or output.
- Internal operator credentials.
- A private trace containing user content.
The gateway can store a payment reference and pass an opaque input reference to the runner. The runtime can fetch the input from a protected store after payment admission. That design limits exposed data to the payment reference and necessary settlement metadata, although the facilitator may still observe payer, recipient, amount, network, asset, and timing.
What to monitor
Track facilitator latency and unknown settlement states beside runner health, and pause Job admission while settlement remains unresolved.
| Signal | What it tells you | Action |
|---|---|---|
| Verification latency | Whether clients can complete the 402 retry | Route or investigate before timeouts rise |
| Settlement latency | Whether paid jobs can be admitted | Hold execution when state is unknown |
| Rejection rate | Whether tokens, domains, or signatures are wrong | Compare by network, scheme, and provider |
| Unknown-state count | How many payments need reconciliation | Page an owner; do not discard records |
| Provider capability drift | Whether a network or scheme changed | Refresh the agent profile and route table |
| Settlement-to-result gap | Whether admitted jobs finish | Inspect the runner and recovery as well as payment |
A trace for a paid request should include facilitator choice, verification result, settlement reference, and job outcome. Redact the authorization and user payload according to the payment provider’s retention policy.
An evaluation can test the whole path with a small controlled payment. It should assert that an invalid authorization does not execute, a valid authorization produces one job, a repeated request is idempotent, and an unknown settlement state pauses execution.
Failure cases to rehearse
The facilitator returns a valid-looking response for the wrong resource. Bind verification to the job identity, amount, recipient, network, and request policy. Do not accept a generic “valid” response.
The facilitator is reachable but the chain is congested. Settlement latency can rise while verification remains healthy. Use separate timeouts and surface the difference to the client.
A provider changes a supported token contract. The service should reject the new asset until it is approved in the agent profile and deployment policy.
A client retries after the first settlement response is lost. Look up the existing payment and job before initiating a second effect.
The runner fails after settlement. Persist the payment reference before starting the job and expose a status or recovery endpoint.
A fallback provider supports a different scheme. Issue a new payment requirement and require the client to authorize that exact scheme. Do not reinterpret an old signature.
The facilitator is compromised. Minimize metadata, validate responses against the client authorization, isolate facilitator credentials, and make the resource server fail closed on inconsistencies.
Choose hosted, self-hosted, or local settlement
Choose a hosted facilitator when you need a provider endpoint without operating payment verification, settlement, or chain infrastructure and can accept that provider boundary. Choose self-hosting when payment availability and data handling justify owning the service. Choose local handling only when your team is prepared to own the network integration and failure modes.
The x402 trust-minimizing mechanism is the client’s signed intent plus response checks against the requested amount, recipient, network, and scheme. The resource server remains responsible for whether paid work runs and returns a result.
Does an x402 facilitator hold user funds?
The standard facilitator model is to verify and settle a client authorization rather than hold a custodial balance. The exact custody and key model depends on the provider and payment scheme, so read its current documentation and terms.
Can I run an x402 service without a facilitator?
Sometimes. The supported payment scheme must allow the resource server to verify and settle locally, and the service must own the chain, token, gas, replay, and upgrade concerns.
What should happen when settlement status is unknown?
Do not execute the paid job. Record the payment reference, reconcile through the scheme’s status or idempotency mechanism, and admit work only after settlement is known.
Is a second facilitator enough for high availability?
No. It helps only when capabilities and replay semantics match and the service chooses the fallback before signing or safely reconciles an in-flight settlement.
Does the facilitator verify the AI result?
No. It handles payment checks. Result correctness belongs to the Blueprint’s job-specific verification or evaluation path.
For the buyer-facing unit-price decision that follows settlement design, see pay-per-request API pricing.
Public sources
The x402 protocol repository documents the current resource-server, client, and facilitator flow. The x402 facilitator guide describes the protocol boundary for verification and settlement. The Coinbase facilitator guide describes verify and settle responsibilities. The Tangle x402 gateway shows how a paid request can feed a Blueprint runner. The Tangle pricing and payments guide distinguishes x402 ingress from on-chain service payment. The paid Blueprint job guide explains how a settled request becomes runnable work. The deployment architecture guide covers the remote runner that remains after payment admission.