Skip to main content
The facilitator pays Stellar network fees on behalf of buyers and sellers. This page covers the knobs that control how much it can spend per transaction and in aggregate.

​
The sponsor account

  • One Stellar account per facilitator instance.
  • Holds XLM only. No other assets.
  • Its secret key lives in SPONSOR_SECRET_KEY.
Do not use a personal or hot-wallet key. Create fresh at deployment.

​
Per-transaction ceiling

SPONSOR_FEE_CEILING_XLM caps the Stellar fee the facilitator will pay for one settlement. Two forces pull in opposite directions:
  • Higher ceiling = more resilience to fee spikes, less user-visible failure.
  • Lower ceiling = predictable burn rate, less loss on runaway RPC estimates.
Default is 0.1 XLM. Reasonable production values sit between 0.05 and 0.5. Above that you are almost always paying for an RPC misestimate. When a settlement’s estimated fee exceeds the ceiling, /settle returns fee_ceiling_exceeded. This is one of the recoverable errors and worth surfacing to the seller.

​
Balance alerts

  • SPONSOR_MIN_BALANCE_XLM is the low-water threshold.
  • SPONSOR_ALERT_WEBHOOK receives a POST when balance dips below the threshold.
Size the threshold to at least 24 hours of expected burn. Alert routing should page a human, not fill an inbox.

​
Estimating burn rate

The x402_sponsor_fees_paid_xlm_total counter is monotonic. Over a stable interval:
Use the observed rate for reordering and top-ups, not the estimated one.

​
Charging users

Today, the operator absorbs sponsor cost. If you want to pass fees through, run your own facilitator and factor the cost into your sellers’ quoted prices (e.g. add a percentage to amount in your middleware before responding with PaymentRequirements). The wire protocol has no built-in fee-pass-through.