Skip to main content
The facilitator is the piece of infrastructure that makes an x402 payment possible without the buyer and seller having to speak Stellar directly. It exposes three endpoints (/verify, /settle, /supported) plus the Bazaar’s two discovery endpoints, and everything it does can be described in three verbs: check, sponsor, submit.

​
Check

On /verify the facilitator confirms:
  • The signedAuthEntries are cryptographically valid.
  • They authorize the exact amount, asset, and destination from the PaymentRequirements.
  • The validBefore timestamp has not elapsed.
  • The client account holds enough of the payment asset.
  • The requested scheme and network are supported (see /supported).
If any of these fail, the facilitator returns a machine-readable invalidReason. Every reason lives in the Error & Rejection Codes reference. Stellar transactions require XLM to cover fees. The facilitator wraps every settlement in a Stellar fee-sponsorship envelope, using its sponsor account to pay fees on behalf of the buyer and the seller. That is why:
  • Buyers only need the payment asset (USDC) in their wallet.
  • Sellers receive the full quoted amount, undiscounted for gas.
  • Operators need to keep the sponsor account funded (see Fee Configuration).

​
Submit

On /settle, the facilitator builds the full Soroban transaction, signs it with the sponsor account, and submits it to a Stellar RPC node. It waits for finality (~5 seconds on mainnet) and returns the txHash on success or an errorReason on failure.

​
What the facilitator does not do

  • It does not custody buyer funds. It only ever holds signed authorization entries scoped to a specific transfer.
  • It does not decide prices. Prices come from the seller’s PaymentRequirements.
  • It does not authenticate users. It only verifies payments.
  • It does not retry on the seller’s behalf. If settlement fails, the seller is told and decides what to do.

​
Hosted versus self-hosted

StellarX402 offers a hosted facilitator at https://facilitator.stellarx402.com. You would run your own if:
  • You need on-prem or private-cloud deployment.
  • You want direct control over the sponsor account and fee ceiling.
  • You want a private Bazaar scoped to your organization.
See the operator quickstart to stand one up.