Skip to main content
By the end of this page you know which environment variables the facilitator reads, what each defaults to, and the two settings that most often cause a surprise. This uses @rail402.dev/facilitator, which reads its configuration from environment variables and validates it before the port binds.
Two settings are easy to get wrong. MAX_TRANSACTION_FEE_STROOPS defaults to 100000, which refuses smart-account payments: raise it to roughly 500000 if you serve buyers paying from OpenZeppelin contract accounts. BAZAAR_ALLOW_PRIVATE_HOSTS opens loopback and private-network seller URLs and is for local development only: leaving it on in a public deployment is an SSRF risk.

​
Environment variables

On testnet, the signer is the only variable you need to set, and even that is optional: run with no secret and the facilitator generates an ephemeral testnet signer and funds it from friendbot. See Run the facilitator.

​
The fee ceiling and smart accounts

MAX_TRANSACTION_FEE_STROOPS is a safety circuit breaker, not a price. It caps the simulation-derived settlement fee. A settlement that would exceed the ceiling is refused with a coded reason rather than submitted, so a fee spike can never drain the signer. The default of 100000 stroops covers an ordinary keypair settlement several times over. A payment from a smart-contract account (a __check_auth buyer) costs more, because settlement cross-calls a signature verifier and an on-ledger spending policy. If you serve those buyers, raise the ceiling to roughly 500000:
If legitimate payments are being refused for exceeding the ceiling, this is the value to raise. See smart accounts for what a contract-account buyer is.

​
Private seller hosts

The Bazaar and the buyer-side path refuse to fetch resource URLs that resolve to loopback or private-network addresses, so a listing cannot point the facilitator at an internal host. Set BAZAAR_ALLOW_PRIVATE_HOSTS only when you run a seller on the same machine during development.
Never set BAZAAR_ALLOW_PRIVATE_HOSTS on a public deployment. It disables the guard that keeps a hostile listing from reaching your internal network. See Security and trust boundaries.

​
Fees and the business model

This deployment is free on testnet, and no fee is hard-wired anywhere in the code. The facilitator does not charge the caller and has no usage-based billing to configure. Any pricing an operator adds must be configuration a self-hoster can change or remove, never a value baked into the build. The facilitator sponsors the network fee on every settlement. The extra.areFeesSponsored flag on /supported reflects the actual runtime configuration: it is advertised as true because settlement is genuinely funded by the facilitator, so a stock client that reads the flag is told the truth. The flag is never a claim the runtime cannot back.

​
Next steps

Run the facilitator

Hosted, npx, or Docker, then verify the surface.

Bazaar operations

Durability with CATALOG_DB_PATH and the degraded-mode story.

Security and trust boundaries

Why the private-hosts and fee-ceiling defaults are what they are.

Error reference

Every coded rejection and whether it is retryable.