Facilitator-role engine: verify and settle x402 payments yourself.

While X402.Facilitator is the client of a remote facilitator, this module is the facilitator itself. It assembles the SDK's local verification core (X402.Verify.EVM), JSON-RPC client (X402.RPC), transaction encoder (X402.Transaction), and signer behaviour (X402.Signer) into the engine behind the facilitator API's three operations, speaking the same wire shapes as the reference facilitators:

• verify/3 — the full exact-EVM / upto-EVM verify checklist at :full level, returning the POST /verify response (%{"isValid" => true, "payer" => ...} / %{"isValid" => false, "invalidReason" => ..., "payer" => ...}).
• settle/3 — re-verifies independently (the schemes' normative requirement), then broadcasts the settlement transaction and awaits its receipt, returning the POST /settle response (%{"success" => true, "transaction" => ..., ...} / %{"success" => false, "errorReason" => ..., ...}).
• supported/1 — the GET /supported response derived from the configured networks.

Expose the engine over HTTP with X402.Plug.Facilitator, or call it directly from your own transport.

Payment kinds

The engine settles every EVM flow X402.Verify.EVM verifies:

The requirements select the authorization used throughout verification, settlement, payer reporting, pending lookup, and receipt checking. Extra unsigned authorization objects do not change that selection; a missing selected authorization never falls back to another transfer method.

For upto the requirements' extra.facilitatorAddress must be this engine's signer address (the proxy only accepts the witness facilitator as sender); other facilitators' payments are rejected with upto_facilitator_mismatch. The settled amount is the requirements' amount, which re-verification proves to be at most the signed permitted.amount.

Fee-payer safety

The facilitator's signing key pays gas, so what it signs is structurally constrained: settlement transactions are always built by this module with to set to the verified requirements' asset (EIP-3009) or the fixed x402 Permit2 proxy address (Permit2), value 0, and calldata produced exclusively by X402.EIP3009.transfer_calldata/3 / X402.Permit2.exact_settle_calldata/2 / X402.Permit2.upto_settle_calldata/3 from the authorization fields the signature verification just proved. The single exception is ERC-6492 counterfactual settlement: the engine signs caller-supplied calldata ONLY toward explicitly allowlisted factory addresses (:eip6492_allowed_factories), capped by :max_deploy_gas_limit — with the default empty allowlist it never does, and counterfactual payments are rejected fail-closed at verify and at settle's re-verify. Deployed ERC-1271 smart wallets are fully supported either way.

Settlement pipeline

1. Reconcile: with a :pending_settlement_store configured, a payload whose earlier attempt already broadcast a transaction is re-awaited instead of re-verified and re-broadcast.
2. Re-verify via X402.Verify.EVM at :full level (transfer simulation off by default — verify already simulated; see :simulate_in_settle — while the atomic ERC-6492 counterfactual simulation always runs, being the only possible proof of a counterfactual signature).
3. For a verified counterfactual payment whose wallet is still undeployed, broadcast the wrapper's factory calldata (allowlist-gated, :max_deploy_gas_limit-capped) and require a successful deploy receipt first.
4. Build the settlement calldata — transferWithAuthorization or the proxy's settle (shared with verification's simulation encoding).
5. One batched RPC round-trip: eth_estimateGas (with a safety margin), eth_maxPriorityFeePerGas + eth_feeHistory (falling back to eth_gasPrice on nodes without EIP-1559 fee APIs), and eth_getTransactionCount (pending).
6. Encode the EIP-1559 transaction (X402.Transaction), sign its keccak digest through the configured X402.Signer (the signer must support raw digest signing — X402.Signer.LocalKey does; the 27/28 recovery id it returns is normalized to the EIP-1559 yParity), and broadcast via eth_sendRawTransaction.
7. Poll eth_getTransactionReceipt until confirmation or timeout. A confirmed receipt must also carry the matching ERC-20 Transfer event before success is reported. A broadcast whose confirmation cannot be established returns the spec's non-terminal "settlement_pending" with the transaction hash so callers can reconcile on chain, recording the attempt in the :pending_settlement_store when one is configured.

Hooks

X402.Hooks callbacks wrap both operations, mirroring the reference facilitator's lifecycle hooks: before_* returning {:halt, reason} turns into a rejected wire response (not an exception), after_* runs on successful results and may replace them, and on_*_failure runs for both rejected wire responses and infrastructure errors and may {:recover, result} with a replacement response. The internal re-verify inside settle/3 runs without hooks — the settle hooks already wrap it.

Example

{:ok, rpc} = X402.RPC.new(rpc_url: "https://sepolia.base.org", finch: MyApp.Finch)
{:ok, signer} = X402.Signer.LocalKey.new(System.fetch_env!("PRIVATE_KEY"))

{:ok, engine} =
  X402.Facilitator.Engine.new(
    rpc: rpc,
    signer: signer,
    networks: ["eip155:84532"]
  )

{:ok, %{"isValid" => true, "payer" => payer}} =
  X402.Facilitator.Engine.verify(engine, payment_payload, requirements)

{:ok, %{"success" => true, "transaction" => tx_hash}} =
  X402.Facilitator.Engine.settle(engine, payment_payload, requirements)

Telemetry

Emits [:x402, :facilitator_engine, :verify] and [:x402, :facilitator_engine, :settle] with :status metadata.