The x402 Facilitator: Trust, Uptime, and Safer Failure

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?

These questions come with a facilitator, the payment service in x402, an HTTP payment protocol. The facilitator takes 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, keep the payment reference, and reconcile settlement state before retrying.

On Tangle, the admission point is the Tangle x402 gateway. It pairs gateway behavior with a Blueprint producer so a verified payment can become a runnable job, and it offers a settle-before-execution path. What you observe at the gateway is the settlement result before the runner starts: a settled payment admits one job, and an unknown result holds it. Expensive execution should not begin merely because a client sent a plausible signature.

Choose who owns payment state

An x402 facilitator 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 to avoid operating payment verification, settlement, or chain infrastructure. Self-host when you need control over availability, data handling, and deployment. Use local verification and settlement only when the network and token scheme are 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.

Actors and terms in a paid job

x402 is an open HTTP payment protocol. The client is the agent or application that wants a resource. The resource server 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 executes a job, and 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 joins 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 checks a result against an expected 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 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 /settle

Verification 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. Send only payment metadata and the authorization the scheme requires.

The x402 facilitator documentation and Coinbase facilitator documentation describe these roles. The provider’s current terms and supported networks remain the authority for a deployment.

A Blueprint payment path

agent profile
    |
    | POST /jobs
    v
resource server / x402 gateway
    | \
    |  \-- /verify --> facilitator
    |  \-- /settle --> facilitator --> network
    |
    | settled payment
    v
Blueprint runner -> job router -> runtime -> result

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

Settlement creates an 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, with no verification, settlement, or chain infrastructure to run at first. 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 under its policy. The service also depends on the provider’s latency and incident response. Hosted does not mean untrusted; it means you accept a provider boundary instead of operating it yourself.

Self-hosted facilitator

Self-hosting keeps the facilitator’s 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 pays off when the facilitator is on the critical path for high-volume or high-value requests. It is a poor choice if nobody owns its keys, upgrades, and incident response.

Local verification and settlement

Some payment schemes let the resource server verify and settle directly. That removes the facilitator network hop, so 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 prompts you to decide which boundary the business can own.

A facilitator should not alter the client’s intended recipient or amount without the payment authorization failing. That is the protocol’s trust-minimizing goal. 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 execute

Executing on an unknown result may create unpaid compute. Retrying settlement blindly may duplicate the effect if the scheme is not idempotent. The facilitator and payment scheme must document how to query status or retry safely.

Fallback routing is not automatic

A second provider improves availability only when both providers support the same network, asset, scheme, authorization semantics, reconciliation process, and replay behavior.

Do not send the same authorization to a second settlement endpoint after the first call timed out. Reconcile the original settlement, or use the scheme’s documented idempotency and status mechanism.

Choose 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 and issue a fresh payment requirement. If a settlement is already in flight, reconcile it instead of racing another.

The tradeoff is operational: provider health, capability matching, route selection, and a record of which provider saw the authorization.

A small routing policy

This is illustrative pseudocode, not an x402 SDK interface. It shows the control decisions; the real client and facilitator APIs come from their current official documentation.

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 })
}

Only settled reaches enqueueExactlyOnce.

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 stores a payment reference and passes an opaque input reference to the runner. The runtime fetches the input from a protected store after admission. The exposed data is then the payment reference and 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 stays healthy. Use separate timeouts and surface the difference to the client.

A provider changes a supported token contract. Reject the new asset until the agent profile and deployment policy approve it.

A client retries after the first settlement response is lost. Look up the existing payment and job before starting 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 infrastructure, and you accept that provider boundary. Choose self-hosting when payment availability and data handling justify owning the service. Choose local handling only when your team will own the network integration and its 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 verifies and settles a client authorization rather than holding 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 either 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.