Skip to main content
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.

Install and configure

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