x402 V2 facilitator process — verifies payment payloads and settles transactions on-chain over HTTP.
The facilitator is a trusted third party that acts on behalf of resource servers. It does not hold funds — it only validates payment payloads and broadcasts settlement transactions to the blockchain.
Built on r402 0.17.1. Default features host EIP-155 exact and upto, plus Solana exact. batch-settlement is opt-in. NEAR, XRPL, Hedera, Algorand, Aptos, Keeta, TVM, and Stellar exact are optional Cargo features. This process does not host auth-capture. See Security before using in production.
# Install from crates.io
cargo install facilitator
# Generate a commented config template
facilitator init
# Edit config.toml with your RPC URLs and signer keys, then start
facilitator serveRequires Rust 1.95.
# Using pre-built image
docker run -p 8080:8080 -v ./config.toml:/app/config.toml ghcr.io/qntx/facilitator
# Or build from source (1.0.0 default FEATURES)
docker build -t facilitator .
docker build -t facilitator --build-arg FEATURES=chain-eip155,chain-solana,scheme-upto,telemetry .
docker run -p 8080:8080 -v ./config.toml:/app/config.toml facilitatorProduction stack (Caddy + Watchtower): deploy/. One replica; do not scale — see cache note below.
| Method | Path | Description |
|---|---|---|
GET |
/supported |
List supported payment kinds (version / scheme / network) |
POST |
/verify |
Verify a payment payload against requirements |
POST |
/settle |
Settle an accepted payment on-chain |
GET |
/health |
Process liveness (not part of the x402 protocol) |
There is no GET /. Protocol verify/settle outcomes are HTTP 200 with structured JSON (isValid / success). HTTP 400 is only returned for an unparseable body.
facilitator <COMMAND>
Commands:
init Generate a default TOML configuration file
serve Start the facilitator HTTP server
Options:
-h, --help Print help
-V, --version Print version
facilitator init [OPTIONS]
Options:
-o, --output <PATH> Output path [default: config.toml]
--force Overwrite existing file
facilitator serve [OPTIONS]
Options:
-c, --config <PATH> Path to TOML config file [default: config.toml]
The server loads configuration from a TOML file (default: config.toml). Run facilitator init to generate a template for families compiled into the binary.
host = "0.0.0.0"
port = 8080
log_level = "info"
[signers]
evm = ["$EVM_SIGNER_PRIVATE_KEY"] # hex, 0x-prefixed
solana = "$SOLANA_SIGNER_PRIVATE_KEY" # base58, 64-byte keypair
[chains."eip155:84532"]
rpc = [{ http = "https://sepolia.base.org" }]
receipt_timeout_secs = 20
[chains."solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1"]
rpc = "https://api.devnet.solana.com"Do not add [[schemes]]. Schemes are compile-time (chain-eip155 registers EVM exact; scheme-upto / scheme-batch-settlement register those schemes; chain-solana registers Solana exact). A schemes key is a startup error. This process does not host auth-capture.
Empty [chains], an unknown CAIP-2 namespace, or a family not compiled into the binary is a startup error.
HTTP timeouts: 30 s on /verify, /settle, and /supported; 5 s on /health. Keep receipt_timeout_secs below the 30 s client budget (default 20).
| Variable | Default | Description |
|---|---|---|
HOST |
0.0.0.0 |
Bind address |
PORT |
8080 |
Listen port |
CONFIG |
config.toml |
Config file path (for serve) |
OTEL_* |
— | OpenTelemetry configuration |
| Family | This build | Notes |
|---|---|---|
| EVM (EIP-155) exact | default | Ethereum, Base, and any eip155:<id> with RPC + signer |
| EVM (EIP-155) upto | default (scheme-upto) |
Permit2 usage-based; official TS UptoEvmScheme |
| EVM (EIP-155) batch-settlement | opt-in | r402 MemoryChannelStore is single-process. Pin settle to one replica; do not split the store across workers. |
| EVM (EIP-155) auth-capture | not hosted | Official TS facilitator servers do not register it |
| Solana (SVM) exact | default | Any solana:<genesis> with RPC + base58 keypair |
| NEAR exact | --features chain-near |
Relayers from [signers].near (account_id + secret_key) |
| XRPL exact | --features chain-xrpl |
No facilitator signer; [signers].xrpl is a startup error |
| Hedera exact | --features chain-hedera |
hedera:mainnet / hedera:testnet; no rpc (optional mirror_url / node_url) |
| Algorand exact | --features chain-algorand |
standard-base64 seeds; optional algod_url / algod_token |
| Aptos exact | --features chain-aptos |
32-byte ed25519 hex; optional string rpc |
| Keeta exact | --features chain-keeta |
hex/base64 32-byte seed + indices; no rpc; no mnemonic |
| TON (TVM) exact | --features chain-tvm |
hex/base64 32- or 64-byte key; optional string rpc |
| Stellar exact | --features chain-stellar |
S… secrets; pubnet requires rpc |
| Tron exact | blocked | r402-tron 0.17.1 has no SchemeBuilder<&TronChainProvider> |
SettlementCache (in-memory, TTL 120 s) is per process. MemoryChannelStore exists only if scheme-batch-settlement is built. Pin /settle to one replica; do not scale or put two facilitators behind one Caddy. Watchtower rolling restart does not overlap two copies of this compose service.
| Feature | Default | Description |
|---|---|---|
chain-eip155 |
✓ | EVM exact via r402-evm 0.17.1 |
chain-solana |
✓ | Solana exact via r402-solana 0.17.1 |
scheme-upto |
✓ | Register EVM upto. Requires chain-eip155. Registration-only (does not compile r402-evm modules out). |
scheme-batch-settlement |
Register EVM batch-settlement. Requires chain-eip155. MemoryChannelStore is in-memory per process. |
|
chain-near |
NEAR exact via r402-near 0.17.1 | |
chain-xrpl |
XRPL exact via r402-xrpl 0.17.1 | |
chain-hedera |
Hedera exact via r402-hedera 0.17.1 | |
chain-algorand |
Algorand exact via r402-algorand 0.17.1 | |
chain-aptos |
Aptos exact via r402-aptos 0.17.1 | |
chain-keeta |
Keeta exact via r402-keeta 0.17.1 | |
chain-tvm |
TON exact via r402-tvm 0.17.1 | |
chain-stellar |
Stellar exact via r402-stellar 0.17.1 | |
telemetry |
✓ | OpenTelemetry tracing and metrics |
metrics |
Process HTTP facilitator_http_* via the metrics facade; enables r402-core/metrics for r402_settlement_cache_reserve_total |
The binary does not install a recorder and does not bind Prometheus. Operators attach one (for example metrics-exporter-prometheus). telemetry OTLP (MetricsLayer) does not scrape this facade.
| Name | result |
|---|---|
facilitator_http_verify_total |
valid | invalid | error |
facilitator_http_verify_duration_seconds |
same |
facilitator_http_settle_total |
success | failure | error |
facilitator_http_settle_duration_seconds |
same |
error is HTTP 400, cancelled/504 timeout, and FacilitatorError other than a missing handler. Envelope rejects and no_facilitator_for_network are invalid / failure. This process never increments r402_facilitator_*.
cargo install facilitator --no-default-features --features chain-eip155,chain-solana,scheme-upto
cargo install facilitator --features chain-near,chain-xrpl,chain-hedera,chain-algorand,chain-aptos,chain-keeta,chain-tvm,chain-stellar,metricsSee SECURITY.md for disclaimers, supported versions, and vulnerability reporting.
- r402 — modular Rust SDK for the x402 payment protocol
- x402 Protocol Specification — protocol design by Coinbase
- coinbase/x402 — official reference implementations (TypeScript, Python, Go)
Licensed under either of:
- Apache License, Version 2.0 (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
- MIT License (LICENSE-MIT or https://opensource.org/licenses/MIT)
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this project shall be dual-licensed as above, without any additional terms or conditions.
