From 13664cecfbc21903158ec41917feba4965849843 Mon Sep 17 00:00:00 2001 From: Diego Poveda <131712362+DiegoPoveda01@users.noreply.github.com> Date: Wed, 16 Sep 2026 22:24:38 -0300 Subject: [PATCH 1/3] fix(agentic-payments): warn that self-hosted facilitators underbid mainnet fees The stock ExactStellarScheme bids BASE_FEE (100 stroops) on the settlement transaction and on its fee bump. Mainnet Soroban inclusion fees currently sit around 200 stroops at p10-p99, so self-hosted facilitators pass /verify and then time out on /settle. Document the symptom, how to check the going rate, and a feeBumpSigner workaround until x402-foundation/x402#3503 (or similar) ships. Co-Authored-By: Claude Opus 5 --- skills/agentic-payments/x402.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/skills/agentic-payments/x402.md b/skills/agentic-payments/x402.md index 81623e78..9ac652b8 100644 --- a/skills/agentic-payments/x402.md +++ b/skills/agentic-payments/x402.md @@ -429,6 +429,33 @@ 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` (2.26.0) bids `BASE_FEE` (100 stroops) as the inclusion fee on the settlement transaction and on the fee bump, with no option to change it. Mainnet Soroban transactions often need more to be included. Check the going rate with the RPC's `getFeeStats` (`sorobanInclusionFee`). Tracked in [x402-foundation/x402#3491](https://github.com/x402-foundation/x402/issues/3491), with a proposed `inclusionFeeStroops` option in [#3503](https://github.com/x402-foundation/x402/pull/3503). +- Fix: until a release makes the bid configurable, pass a `feeBumpSigner` whose `signTransaction` rebuilds the fee bump it receives with a higher base fee before signing. The inner transaction and its signatures stay unchanged, and the fee bump account pays the difference: + ```js + import { FeeBumpTransaction, TransactionBuilder } from "@stellar/stellar-sdk"; + import { createEd25519Signer, getNetworkPassphrase } from "@x402/stellar"; + + const NETWORK = "stellar:pubnet"; + const INCLUSION_FEE = "10000"; // stroops; size it from getFeeStats + const base = createEd25519Signer(process.env.FEE_BUMP_SECRET, NETWORK); + const feeBumpSigner = { + ...base, + async signTransaction(xdr, opts) { + const passphrase = getNetworkPassphrase(NETWORK); + const bump = TransactionBuilder.fromXDR(xdr, passphrase); + if (!(bump instanceof FeeBumpTransaction)) return base.signTransaction(xdr, opts); + const rebid = TransactionBuilder.buildFeeBumpTransaction( + base.address, INCLUSION_FEE, bump.innerTransaction, passphrase, + ); + return base.signTransaction(rebid.toXDR(), opts); + }, + }; + // new ExactStellarScheme([signer], { feeBumpSigner }) + ``` + 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. From ac1aa7c72346349adafb81819951179db8dc38b3 Mon Sep 17 00:00:00 2001 From: DiegoPoveda01 Date: Tue, 6 Oct 2026 23:07:48 -0300 Subject: [PATCH 2/3] docs(agentic-payments): use inclusionFeeStroops for the mainnet fee pitfall x402-foundation/x402#3503 merged and shipped in @x402/stellar 2.27.0, so the bid is now configurable. The fix becomes the inclusionFeeStroops option, with a note that /verify counts the bid against maxTransactionFeeStroops. The custom feeBumpSigner snippet is reduced to a one-line note for 2.26.0 and earlier. Co-Authored-By: Claude Opus 5.5 --- skills/agentic-payments/x402.md | 29 ++++++++--------------------- 1 file changed, 8 insertions(+), 21 deletions(-) diff --git a/skills/agentic-payments/x402.md b/skills/agentic-payments/x402.md index 9ac652b8..4455f96e 100644 --- a/skills/agentic-payments/x402.md +++ b/skills/agentic-payments/x402.md @@ -431,29 +431,16 @@ The checklist above assumes OZ Channels: it is the mainnet facilitator Stellar's **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` (2.26.0) bids `BASE_FEE` (100 stroops) as the inclusion fee on the settlement transaction and on the fee bump, with no option to change it. Mainnet Soroban transactions often need more to be included. Check the going rate with the RPC's `getFeeStats` (`sorobanInclusionFee`). Tracked in [x402-foundation/x402#3491](https://github.com/x402-foundation/x402/issues/3491), with a proposed `inclusionFeeStroops` option in [#3503](https://github.com/x402-foundation/x402/pull/3503). -- Fix: until a release makes the bid configurable, pass a `feeBumpSigner` whose `signTransaction` rebuilds the fee bump it receives with a higher base fee before signing. The inner transaction and its signatures stay unchanged, and the fee bump account pays the difference: +- 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 - import { FeeBumpTransaction, TransactionBuilder } from "@stellar/stellar-sdk"; - import { createEd25519Signer, getNetworkPassphrase } from "@x402/stellar"; - - const NETWORK = "stellar:pubnet"; - const INCLUSION_FEE = "10000"; // stroops; size it from getFeeStats - const base = createEd25519Signer(process.env.FEE_BUMP_SECRET, NETWORK); - const feeBumpSigner = { - ...base, - async signTransaction(xdr, opts) { - const passphrase = getNetworkPassphrase(NETWORK); - const bump = TransactionBuilder.fromXDR(xdr, passphrase); - if (!(bump instanceof FeeBumpTransaction)) return base.signTransaction(xdr, opts); - const rebid = TransactionBuilder.buildFeeBumpTransaction( - base.address, INCLUSION_FEE, bump.innerTransaction, passphrase, - ); - return base.signTransaction(rebid.toXDR(), opts); - }, - }; - // new ExactStellarScheme([signer], { feeBumpSigner }) + 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. + On 2.26.0 and earlier 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** From 84d2ae4162868da28871454a14e29ec7df513bd2 Mon Sep 17 00:00:00 2001 From: "stellar-triage-bot[bot]" <333411864+stellar-triage-bot[bot]@users.noreply.github.com> Date: Wed, 7 Oct 2026 02:19:28 +0000 Subject: [PATCH 3/3] docs(agentic-payments): scope the fixed 100-stroop bid to 2.19.0-2.26.0 Releases 2.6.0 through 2.18.0 bid the client transaction's fee, capped at maxTransactionFeeStroops, so the fixed BASE_FEE bid only applies from 2.19.0 until inclusionFeeStroops shipped in 2.27.0. --- skills/agentic-payments/x402.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/agentic-payments/x402.md b/skills/agentic-payments/x402.md index 4455f96e..56f509d9 100644 --- a/skills/agentic-payments/x402.md +++ b/skills/agentic-payments/x402.md @@ -440,7 +440,7 @@ The checklist above assumes OZ Channels: it is the mainnet facilitator Stellar's }); ``` `/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. - On 2.26.0 and earlier the bid is fixed at 100 stroops. Upgrade, or pass a `feeBumpSigner` that rebuilds the fee bump with a higher base fee before signing. + 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**