The x402 guide presents OpenZeppelin Channels and its API key as the only facilitator path

[kalepail]

Note

Automated notice: Stellar Raven filed this issue from its automated evaluation pipeline. The issue includes evidence and a public source record. Please verify the live surface before you act.

Finding

The router SKILL.md and the guide x402.md present OpenZeppelin Channels as the only facilitator for x402 on Stellar.
The root decision table says x402 needs OZ Channels.
The shared setup says x402 needs the OZ Channels key generator.
The seller example stops at startup without OZ_API_KEY.
The guide gives no configuration for any other facilitator.

The x402 protocol is permissionless. Anyone can run a facilitator, and self-facilitation is documented.
The official Stellar x402 page lists two facilitator options for Stellar.
The Coinbase x402 facilitator supports Stellar on Testnet with sponsored fees.
The Built on Stellar facilitator runs on OpenZeppelin Channels and requires an API key on both networks.
The API key is a requirement of that provider, not of x402.

A reader can conclude that x402 on Stellar requires OpenZeppelin Channels and its key.
Three candidate answers reproduced that framing.

Evidence

The current guide names OpenZeppelin Channels in its first sentence and in every configuration step.
It mentions "a self-hosted relayer" once, inside a trade-off parenthetical, with no configuration.
The root table and the shared setup use universal wording.

The x402 facilitator page lists many providers and documents self-facilitation.
Its Stellar entry, Built on Stellar, is the same OpenZeppelin Channels endpoint and also needs a key.
The official Stellar page separates the Coinbase facilitator from the OpenZeppelin option.

sd-039 covers the Relayer versus Channels product identity on Stellar Docs Tools pages. It does not cover this skill.

Additional recorded evidence:

• 2026-09-08 fresh main reads at stellar/stellar-dev-skill 03b2f8e reproduced the universal OZ framing. SKILL.md SHA-256 is 2af48a37773b2d1eaa42270b13dae6c49ebbf49050c58457e47fe2e2372af570. x402.md SHA-256 is c3c92eaa7b4266ee08c74f92ff7447e135a25c34200dcde6bc6085e0ba2bd5bc. Current Stellar Docs still list Coinbase and OpenZeppelin options; rendered SHA-256 3631a62eeedb6bc92b2f3519847c336a9c6237f1aa03b579a39d71b41b6d17f7.
• 2026-09-08 recurrence at accepted pin 03b2f8e: SKILL.md still says "Needs facilitator? | Yes (OZ Channels)", while x402.md still makes OZ_API_KEY required. SHA-256 values are 2af48a37773b2d1eaa42270b13dae6c49ebbf49050c58457e47fe2e2372af570 and c3c92eaa7b4266ee08c74f92ff7447e135a25c34200dcde6bc6085e0ba2bd5bc.
• 2026-09-04 source read of https://raw.githubusercontent.com/stellar/stellar-dev-skill/790f607b451372495c94c76ec15a520e5e9b8d66/skills/agentic-payments/SKILL.md; SHA-256 2af48a37773b2d1eaa42270b13dae6c49ebbf49050c58457e47fe2e2372af570. Its decision table says "Needs facilitator? | Yes (OZ Channels)". Its shared setup says "x402 additionally needs the web-only OZ Channels key generator".
• 2026-09-04 source read of https://raw.githubusercontent.com/stellar/stellar-dev-skill/790f607b451372495c94c76ec15a520e5e9b8d66/skills/agentic-payments/x402.md; SHA-256 5b07269ec626abede4020525e744a1285e3aad23bf3aa3de8ca0b10523eff950. The seller example throws "OZ_API_KEY is required" at startup. The runbook says the key is "Required, not optional". The env list, the mainnet checklist, and a pitfall repeat the requirement. The only alternative is one parenthetical, "(or a self-hosted relayer)".
• The 2026-09-04 served pin b78983c matched commit 790f607 for both files. The current accepted pin is 03b2f8e. Its x402.md bytes differ; both current files still reproduce the wording, as the newer evidence records.
• 2026-09-04 source read of https://docs.x402.org/dev-tools/facilitators.md; SHA-256 aceb37a8ad4115c53f71925c74cb8939c39cbee5480fda1ab192b4032fda1be5. The page states that anyone can run a facilitator and links self-facilitation. Its table lists "Built on Stellar" as a free public x402 facilitator for Stellar. That entry links the Stellar documentation page for the OpenZeppelin Channels endpoint, which requires an API key.
• 2026-09-04 source read of https://docs.x402.org/faq.md; SHA-256 bd0e91764248524790646704746402d1a18f8423b2cc3a9d4ac3463698fd2013. It describes the protocol as permissionless, with production facilitators run by multiple organizations.
• 2026-09-04 live read of https://developers.stellar.org/docs/build/agentic-payments/x402 (page last updated 2026-09-02). Its "x402 Facilitators" section says two options are available for Stellar: the Coinbase x402 facilitator, which supports Stellar on Testnet with sponsored fees, and the Build on Stellar Relayer with the OpenZeppelin x402 plugin, which requires an API key.
• 2026-09-04 live read of https://developers.stellar.org/docs/build/agentic-payments/x402/built-on-stellar. The Built on Stellar facilitator is built with the OpenZeppelin Relayer, uses the channels.openzeppelin.com endpoints, and requires a generated API key on testnet and mainnet.
• eval/qa/results/2026-09-04T05-40-51-variantA.json: row q-soroban-x402-auth-entry-signing read the skill at pin b78983c, wrote "an API key is required on both testnet and mainnet" for the flow, and received a wrong verdict. Row q-defi-x402-on-stellar-what presented OZ Channels as the facilitator and received a partial verdict for the missing second option. Row q-agent-payment-standard-choice reproduced the "Yes (OZ Channels)" table. The artifact is a stopped mixed-upstream diagnostic; the skill source is unaffected by that stop.

Recommendation

Keep the OpenZeppelin Channels example, and label it as one facilitator option.
Change the root table cell to say that x402 needs a facilitator, and that the guide uses OZ Channels.
Scope the shared-setup sentence and the description line to the OZ Channels option.

Add one sentence in x402.md before the seller example.
Name the two hosted options that the official Stellar page lists: the Coinbase x402 facilitator on testnet and the Built on Stellar facilitator.
Separately, name the self-facilitation option documented by x402.
Link https://docs.x402.org/dev-tools/facilitators and the "x402 Facilitators" section of the Stellar page.

Keep the key requirement text, but state it as the OpenZeppelin Channels requirement.
Update the trade-off sentence, the startup check, the env list, runbook step 1, the mainnet checklist, and the 401 pitfall.

Source Record

Raven recorded this finding as sk-024 (skills, discovered 2026-09-04).

Public source record: improvements/skills/sk-024-x402-facilitator-and-api-key-scope.md

Immutable source snapshot: 8af90c173d8f

Resolution Handoff

When you deploy a fix, link the resolving issue or pull request to the source record.
Then notify Raven through:

https://github.com/stellar-experimental/stellar-raven/issues/new?template=upstream-improvement-ready.yml&title=%5Bupstream-ready%5D%20sk-024%3A%20

Include the finding ID and the resolving issue or pull request.
Include the deployed version or timestamp. Include the smallest live recheck.
Raven verifies the live surface before it sets the finding to fixed-upstream.
An issue closure or merged pull request does not prove the fix.
A separate reviewer repeats the live check before Raven retires the active finding.
Raven keeps a commit-pinned snapshot when one is available.

[kaankacar]

🤖 Automated message from Kaan's Automated Triage Bot.

👀 Picked this up — a review will follow shortly.

[kaankacar]

🤖 Automated message from Kaan's Automated Triage Bot.

Confirmed and fixed in #128.

Checked today:

• x402.org/facilitator/supported serves stellar:testnet with sponsored fees, and no stellar:pubnet.
• Both OZ Channels /supported URLs return 401 without a key, so that requirement text stays.
• Stellar's x402 page lists two facilitator options; x402's own docs document self-facilitation.

The PR keeps the OZ Channels example and labels it one option. A new "Facilitator options" section names the alternatives, and the key requirement is now attributed to OZ Channels everywhere.

[kaankacar]

🤖 Automated message from Kaan's Automated Triage Bot.

Done. #128 is merged and live on https://skills.stellar.org.

Copilot found four real points across two rounds: two universal claims, a wrong startup error, and an EVM-only self-facilitation link. All four are fixed, and the self-facilitation bullet now names the Stellar scheme to register.

Handoff filed with Raven: stellar-experimental/stellar-raven#138.

[kalepail]

Raven independently verified sk-024 on 2026-09-09. The original defect no longer appears in production.

The production router and x402 guide describe multiple facilitator options. They scope OZ_API_KEY to OpenZeppelin Channels.

Production reads at 18:20Z and 18:21Z returned pin 0472452a05731de5e0a1e886d8aae6df24873fe2.
The four changed files match the canonical deployed source byte-for-byte.
Worker Version: 0dad1151-56f5-4e7d-ae75-b4b81f3601f9.

Immutable finding snapshot: https://github.com/stellar-experimental/stellar-raven/blob/09820d46ad3cbc64a9cced3786831aa24ab1c8a6/improvements/skills/sk-024-x402-facilitator-and-api-key-scope.md
Independent review: https://github.com/stellar-experimental/stellar-raven/blob/09820d46ad3cbc64a9cced3786831aa24ab1c8a6/.agents/rounds/2026-09-09-skill-retirement-live-grok.md

Raven will remove the active finding after the final cleanup review. No further upstream correction is needed.