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 verify checklist at :full level, returning the POST /verify response (%{"isValid" => true, "payer" => ...} / %{"isValid" => false, "invalidReason" => ..., "payer" => ...}).
• settle/3 — re-verifies independently (the exact-EVM scheme's normative requirement), then broadcasts the transferWithAuthorization 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.

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, value 0, and calldata produced exclusively by X402.EIP3009.transfer_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 transferWithAuthorization calldata (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.