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

[DiegoPoveda01]

Adds a "Common pitfalls" entry to skills/agentic-payments/x402.md for self-hosted facilitators on stellar:pubnet: /verify passes, but /settle times out.

Why

ExactStellarScheme in @x402/stellar/exact/facilitator (latest, 2.26.0) bids BASE_FEE (100 stroops) as the inclusion fee on the settlement transaction and on its fee bump, and there is no option to change it. On testnet that is enough. On mainnet it often isn't, and the transaction never lands. An agent following the skill today would ship a facilitator that works on testnet and then silently fails on mainnet.

What was checked against live sources

• getFeeStats on a pubnet RPC (last 50 ledgers, ~3.9k txs): sorobanInclusionFee min 100, mode 200, p10 through p99 all 200. A 100-stroop bid sits at the floor.
• Repro from a real project (Local402):
  • With the stock facilitator, settle timed out on pubnet.
  • With the fee bump re-bid shown in the entry, it settled: tx a220bdf9…106e.
  • Details are in x402-foundation/x402#3491.
• The snippet was run against @stellar/stellar-sdk and @x402/stellar 2.26.0 on a throwaway key.
  • A fee bump built at 100 comes back at INCLUSION_FEE per operation.
  • The inner transaction and its signatures are unchanged.
  • The wrapper keeps the rest of the signer (address, signAuthEntry).
• The upstream fix is proposed in x402-foundation/x402#3503 as an inclusionFeeStroops option. Once a release includes it, the entry's Fix can point to that option instead of the workaround.

The entry sits before the browser-signing pitfall and follows the Symptom / Cause / Fix shape of the other entries. No other files changed.

AI disclosure

This change was drafted with Claude Code. I reviewed the text, and the fee data and the snippet were checked as described above.

🤖 Generated with Claude Code

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[kaankacar]

🤖 Automated message from Kaan's Automated Triage Bot.

👀 Picked this up — a review will follow shortly.

[stellar-triage-bot]

🤖 Automated message from Kaan's Automated Triage Bot.

Thanks for this, Diego. It is a real mainnet trap, and you fixed it upstream too. I checked the entry against the published package:

• @x402/stellar 2.26.0 hardcodes BASE_FEE on the settlement transaction and on the fee bump. Your workaround matches that code, and the fee bump XDR it returns is submitted as is.
• Live pubnet getFeeStats shows sorobanInclusionFee min 100 and mode 200, so a 100 bid sits at the floor.
• Your mainnet tx a220bdf9…106e is a successful fee bump at a 1,000 stroop bid.

One thing changed after you opened this. Your upstream PR x402-foundation/x402#3503 merged on 2026-09-17. inclusionFeeStroops shipped in 2.27.0, and npm latest is now 2.28.0. The skill's install lines are unpinned, so readers get 2.28.0 today. That makes two parts of the entry out of date:

1. "with no option to change it" and "until a release makes the bid configurable" are no longer true.
2. The Fix should be an option, for example new ExactStellarScheme([signer], { inclusionFeeStroops: 1000 }). The option sets both the settlement bid and the fee bump bid. The Fix should also say that verify counts the bid against maxTransactionFeeStroops (default 50,000), so a high bid can need a higher ceiling.

I suggest you drop the custom signer snippet, or keep it only as a short note for 2.26.0 and earlier. Could you update the entry? I will re-check it after your push.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[stellar-triage-bot]

🤖 Automated message from the Stellar Triage Bot.

Thanks, Diego. The new Fix is clear, and it now points readers at your upstream option. I checked it against the published @x402/stellar code:

• 2.27.0 and 2.28.0 take inclusionFeeStroops (default 100). It sets the settlement bid and the fee bump bid.
• /verify adds the bid to minResourceFee and rejects with invalid_exact_stellar_payload_fee_exceeds_maximum above maxTransactionFeeStroops (default 50,000).
• Live pubnet getFeeStats still shows sorobanInclusionFee min 100, mode 200.

I pushed one small fix (84d2ae4). The fixed 100-stroop bid starts in 2.19.0. Releases 2.6.0 to 2.18.0 bid the client's own fee, capped at the ceiling. So the note now says "From 2.19.0 through 2.26.0".

Copilot could not review (quota), so there were no review points to weigh. Merging now.

[stellar-triage-bot]

Verified against @x402/stellar 2.19.0-2.28.0 and live pubnet fee stats.