x402 facilitator security

In x402, the resource server decides whether a request is paid, but it rarely checks signatures or talks to a blockchain itself. It hands the client's payment to a facilitator: a service that verifies the authorization and settles it on a network. The x402 V2 core specification lets a resource server delegate this to a third party or host the endpoints itself. Either way, a facilitator error decides whether paid content leaks for free or a client pays twice.

The three facilitator endpoints

Both POST endpoints take the same body: x402Version, the client's paymentPayload and the paymentRequirements it should satisfy. The resource server should send its own requirement there, not the copy the client echoed in accepted.

When /verify runs: payment flows

The payment flow decides which endpoints run, and in which order, around the resource handler:

The specification's invariant: a verify or a settle must run before the resource executes. Under the default flow, that makes /verify the only thing standing between a forged signature and the protected handler.

What goes wrong

These are risks to look for in any facilitator, with the control the specifications imply for each.

One thing a facilitator cannot do on the EVM exact scheme is change the amount or the destination: both are inside the payer's signed message, and the scheme specification limits the facilitator to broadcasting the transaction.

What Settlens tests

A facilitator scan reads GET /supported passively. The /verify checks run only during an active probe that the endpoint owner authorized in writing. The table is generated from the Settlens check catalog.

Two runs against the bundled demo target show the checks that matter most. Here the facilitator does not list the Base Sepolia kind that the resource advertises:

$ settlens scan http://127.0.0.1:4402/secure \
    --facilitator http://127.0.0.1:4402/facilitator-empty --no-write
Settlens x402 assessment 96327c63
Targets 1 · Active 0 · Settlement calls 0
 
127.0.0.1  GET http://127.0.0.1:4402/secure
22 pass · 1 fail · 0 warn · 0 skip
  FAIL high     Facilitator covers advertised payment requirements
       1 advertised payment choice(s) are absent from facilitator capabilities.
 
Total: 22 pass · 1 fail · 0 warn · 0 skip

Here the facilitator's /verify answers isValid: true to an all-zero signature. The probe sends that one invalid payload and never calls /settle:

$ settlens scan http://127.0.0.1:4402/secure \
    --facilitator http://127.0.0.1:4402/facilitator-accept \
    --active --authorized --authorization-ref DEMO-APPROVAL-003 --no-write
Settlens x402 assessment 513cfb74
Targets 1 · Active 1 · Settlement calls 0
 
127.0.0.1  GET http://127.0.0.1:4402/secure
26 pass · 1 fail · 0 warn · 0 skip
  FAIL critical Facilitator /verify rejects an invalid signature
       The facilitator reported isValid=true for an intentionally invalid, all-zero signature.
 
Total: 26 pass · 1 fail · 0 warn · 0 skip

What an outside test cannot prove

• Settlement. Settlens never calls /settle and never moves funds, so it cannot show that a facilitator settles the right amount once, or handles settlement_pending correctly.
• Chain state. Balance checks, nonce use and transaction simulation need an RPC node; Settlens works without one.
• Read-only /verify. A single invalid probe cannot observe whether /verify writes state for valid payloads.
• Valid payments. The probe proves that one forged signature is rejected, not that every valid payment is accepted.

For these, review the facilitator's code and settlement records. The facilitator section of the x402 security checklist lists every control, and Settlens for facilitators describes how operators use the scans. Check ids and fixes are in the check reference.

Frequently asked questions