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

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.