Skip to content

fix(agentic-payments): warn that self-hosted facilitators underbid mainnet fees #134

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
stellar-triage-bot merged 3 commits into from
Oct 7, 2026
Merged

fix(agentic-payments): warn that self-hosted facilitators underbid mainnet fees #134

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
13664ce
fix(agentic-payments): warn that self-hosted facilitators underbid ma…
DiegoPoveda01 Sep 17, 2026
ac1aa7c
docs(agentic-payments): use inclusionFeeStroops for the mainnet fee p…
DiegoPoveda01 Oct 7, 2026
84d2ae4
docs(agentic-payments): scope the fixed 100-stroop bid to 2.19.0-2.26.0
stellar-triage-bot[bot] Oct 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions skills/agentic-payments/x402.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -429,6 +429,20 @@ The checklist above assumes OZ Channels: it is the mainnet facilitator Stellar's
- Symptom: `op_no_trust` during settlement, even though the client has USDC
- Fix: the `payTo` account needs a USDC trustline too. The SAC `transfer` settles the underlying classic asset, which the recipient cannot hold without a trustline. Add `changeTrust` to both accounts during setup.

**Self-hosted facilitator: mainnet settlement times out after verify passes**
- Symptom: on `stellar:pubnet`, `/verify` returns valid but `/settle` never completes, and no transaction from the facilitator account reaches the ledger. The same setup works on testnet.
- Cause: `ExactStellarScheme` from `@x402/stellar/exact/facilitator` bids `BASE_FEE` (100 stroops) as the inclusion fee on the settlement transaction and on the fee bump unless told otherwise. Mainnet Soroban transactions often need more to be included. Check the going rate with the RPC's `getFeeStats` (`sorobanInclusionFee`). See [x402-foundation/x402#3491](https://github.com/x402-foundation/x402/issues/3491).
- Fix: set `inclusionFeeStroops` (available from 2.27.0). It sets the bid on both the settlement transaction and the fee bump:
```js
new ExactStellarScheme([signer], {
inclusionFeeStroops: 1000, // size it from getFeeStats
maxTransactionFeeStroops: 50_000, // default; raise it if the bid needs headroom
});
```
`/verify` adds the bid to the simulated resource fee and rejects the payment (`invalid_exact_stellar_payload_fee_exceeds_maximum`) if the total is over `maxTransactionFeeStroops`. A high bid can therefore need a higher ceiling.
From 2.19.0 through 2.26.0 the bid is fixed at 100 stroops. Upgrade, or pass a `feeBumpSigner` that rebuilds the fee bump with a higher base fee before signing.
Hosted facilitators set their own fees, so this only applies when you run `ExactStellarScheme` yourself.

**Trying to sign auth entries from a browser**
- Symptom: bundling errors, or a browser wallet that has no API to sign contract auth entries
- Fix: run the x402 client server-side (e.g. an Express route the browser calls), or use Wallets-Kit / Freighter with custom auth-entry signing. `@x402/fetch` + `createEd25519Signer` target Node and assume a raw secret key.
Expand Down