Use the embedded package when a seller wants one process instead of a separate
facilitator HTTP hop. It uses the same verification, channel leases, fee
budgets, idempotency records, and unknown-transaction recovery as the standalone
service.
The embedded path still requires PostgreSQL. This is deliberate: replay
protection, sponsor budgets, sequence locks, and settlement recovery must
survive a process restart and work across replicas.
Provide DATABASE_URL, FACILITATOR_CONFIG, and
FACILITATOR_KEY_ENCRYPTION_KEY as you would for the standalone service.
Minimal Express server
The exact exported helper and lifecycle are shown in
facilitator/examples/self-facilitating-resource-server. Keep the example’s
shutdown handling in production so leases and database connections drain
cleanly.
Boundary
Embedded facilitation removes the network hop only. The process still:
- re-verifies at settlement;
- rebuilds the Stellar transaction with a channel account;
- sponsors the fee through a fee-bump envelope;
- enforces resource, inclusion, total, concurrency, and sponsor budgets;
- persists the envelope before submission;
- polls a known hash after an ambiguous RPC response; and
- returns the same x402 wire responses as the HTTP facilitator.
The embedded facilitator never becomes the payer or recipient and never holds
the seller’s payment asset.
When to choose it
Choose embedded facilitation for a single seller or a tightly coupled private
deployment. Choose the standalone facilitator when several sellers share one
catalog, when operators need independent scaling, or when the facilitator must
be upgraded without redeploying seller applications.
See self-hosting for the one-service deployment and
security for key, fee, and recovery invariants. Last modified on August 10, 2026