Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
Adds the pre-production Vellar facilitator to Stellar’s x402 documentation.
Changes:
- Adds a Community facilitators subsection.
- Documents Vellar’s discovery, MCP tooling, fee sponsorship, links, and status.
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
- Intro sentence now accounts for the community subsection instead of claiming two options. - Bazaar cataloging happens only when the settled payment's payload carries the discovery extension; say so, and note that payments without it settle normally but are not cataloged. - The MCP discovery server is a separate stdio process run locally and pointed at the facilitator URL; the hosted instance has no MCP endpoint. - The open external audit blocks a mainnet release tag, not running a mainnet instance; reword the status note to match the project's own checklist.
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.
Suppressed comments (1)
docs/build/agentic-payments/x402/README.mdx:110
- Carrying the Bazaar extension does not guarantee that the resource is added: the facilitator can still reject cataloging for invalid discovery data, an unbound
payTo, or an ownership-binding mismatch while allowing settlement to succeed. Please describe cataloging as conditional so sellers do not treat a successful extended settlement as proof that they were listed.
endpoints with a **Bazaar discovery layer**: when a payment settles and its
payload carries the Bazaar discovery extension, the resource is added to a
searchable catalog, so sellers that use the extension are listed without a
The note said an external security audit was still open. The facilitator's pre-mainnet security review is complete with findings tracked to closure; the remaining gate on a mainnet release is a separate audit of the spending-limit policy contract, which has not been run. The other three review points (facilitator count, Bazaar extension requirement for cataloging, and MCP being a separate stdio server) were already addressed in aa3268c.
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.
Suppressed comments (1)
Previously missed (1) — in code that hasn't changed since the last review.
docs/build/agentic-payments/x402/README.mdx:117
- Fee sponsorship does not mean every buyer can hold no XLM. A classic account holding the payment asset normally still needs XLM for its account and trustline reserves unless those reserves are separately sponsored (
docs/learn/fundamentals/lumens.mdx:30-40), while this facilitator only sponsors the settlement transaction fee. Please limit the claim to that fee.
The intro to the facilitators section still said two options were available while listing three, which left the community entry reading as an afterthought rather than part of the count. It now says two production implementations plus one community-run pre-production option. The other three Copilot comments were already addressed on this branch: cataloging is stated as conditional on the payload carrying the Bazaar discovery extension, MCP is described as a separate local stdio server rather than an endpoint on the hosted URL, and the mainnet statement already separates the completed facilitator review from the outstanding policy contract audit.
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.
Suppressed comments (3)
docs/build/agentic-payments/x402/README.mdx:117
- Fee sponsorship does not mean every buyer can hold zero XLM. Classic Stellar accounts must maintain their base reserve, and an asset trustline adds another reserve unless those reserves are separately sponsored (
docs/learn/fundamentals/lumens.mdx:28-40). Since Vellar supports classic-keypair buyers, narrow this claim to transaction fees.
facilitator sponsors the network fee on settlement, so buyers hold only the
payment asset and no XLM.
docs/build/agentic-payments/x402/README.mdx:129
- This understates the remaining audit scope. Vellar's current mainnet checklist marks an external audit of the facilitator as not started, while its technical plan says that review covers the facilitator and all three provenance contracts, not only the spending-limit contract (
technical-doc.md:591-609,technical-doc.md:679-684). Please describe the full gate so readers do not infer that the other components have already passed an independent review.
findings tracked to closure. A mainnet release is additionally gated on a
separate audit of the spending-limit policy contract, which has not yet been
run. The hosted instance runs on a free tier, so the first request after an
docs/build/agentic-payments/x402/README.mdx:128
- The linked project's current
docs/security-audit.mdexplicitly keeps F6 open (“RELOCATED, not eliminated”) and distinguishes open/deferred/external findings, so “findings tracked to closure” overstates the review outcome. Please describe the review as complete while preserving that some residual risks remain documented.
instance. The pre-mainnet security review of the facilitator is complete, with
findings tracked to closure. A mainnet release is additionally gated on a
separate audit of the spending-limit policy contract, which has not yet been
Three corrections, all verified against the facilitator repo: 1. Cataloging is conditional, not automatic. Carrying the Bazaar extension does not guarantee a listing: it is refused for invalid discovery data or when the resource URL is already bound to a different recipient, while settlement succeeds either way. 2. Fee sponsorship covers the settlement transaction fee only. Classic Stellar accounts still maintain their own base and trustline reserves, so the previous 'no XLM' claim was too broad. 3. Audit scope corrected. The completed review is internal, and F5/F6/F8 remain open or deferred rather than closed. The external audit covers the facilitator and its three provenance contracts, not the spending-limit contract alone, and has not been commissioned.
Wrapped paragraphs were reformatted to single lines by prettier --write, matching the repo's configured proseWrap setting. No content changes.
ElliotFriend
requested changes
Sep 16, 2026
ElliotFriend
left a comment
ElliotFriend
left a comment
Contributor
There was a problem hiding this comment.
Thanks for this, and for filing it as a draft with your reasoning written out. That made it much easier to review.
To answer your open question up front: yes, a community section would definitely be welcome on this page. You did a great job framing the section as a whole, as well as Vellar's current status.
My main note is length. The other entries at this page currently sit at 34 words for Coinbase, and 190 for Build on Stellar. this one is much longer, and that could be misconstrued as endorsement or maturity to the reader.
I've left suggestions inline for the specifics. Once those are in, I'm happy to get this merged.
Thanks again!
| ## x402 Facilitators | ||
|
|
||
| You can use a facilitator to verify and settle x402 payments. Two options are available for Stellar: | ||
| You can use a facilitator to verify and settle x402 payments. Two production implementations are available for Stellar, plus one community-run pre-production option listed at the end of this section: |
Contributor
There was a problem hiding this comment.
i think this might actually be best if we take out the numbers altogether. something simpler like The following options are available for Stellar: might serve us well, and it won't have to be changed if things are added/removed down the road.
|
|
||
| :::note | ||
|
|
||
| Vellar runs on **Testnet only** and is pre-production; there is no mainnet instance. The facilitator has completed an internal pre-mainnet security review, with most findings closed and the remainder documented as open or deferred. A mainnet release is separately gated on an external audit covering the facilitator and its three provenance contracts, which has not yet been commissioned. The hosted instance runs on a free tier, so the first request after an idle period can take up to a minute. |
Contributor
There was a problem hiding this comment.
there's a lot of detail here that isn't really necessary for this listing. also, its three provenance contracts don't mean all that much to a reader who isn't already familiar with vellar. we could simplify this to something like:
Suggested change
| Vellar runs on **Testnet only** and is pre-production; there is no mainnet instance. The facilitator has completed an internal pre-mainnet security review, with most findings closed and the remainder documented as open or deferred. A mainnet release is separately gated on an external audit covering the facilitator and its three provenance contracts, which has not yet been commissioned. The hosted instance runs on a free tier, so the first request after an idle period can take up to a minute. | |
| Testnet only, and not independently audited. See the Vellar's security notes for more information. |
a link somewhere in there to a specific place to see the closed/open/deferred findings, and/or the progress of any audits could be helpful, as well.
|
|
||
| [Vellar](https://github.com/Vellar-Wallet/vellar-facilitator) is an Apache-2.0 x402 facilitator that pairs the standard `/verify`, `/settle`, and `/supported` endpoints with a **Bazaar discovery layer**: when a payment settles and its payload carries the Bazaar discovery extension, the facilitator may add the resource to a searchable catalog, so sellers that use the extension are listed without a separate registration step. Cataloging is conditional and can be refused for invalid discovery data, or when the resource URL is already bound to a different recipient; settlement succeeds either way, and payments without the extension settle normally but are never cataloged. The catalog is also reachable by AI agents through an [MCP](https://modelcontextprotocol.io) discovery server (`src/mcp.ts` in the repository), which is a separate stdio process you run locally and point at the facilitator URL; the hosted instance does not expose an MCP endpoint itself. The facilitator sponsors the settlement transaction fee, so buyers do not need XLM to pay for the transaction itself. Classic Stellar accounts still maintain their own base and trustline reserves. | ||
|
|
||
| - **Facilitator**: `https://vellar-facilitator.onrender.com` |
Contributor
There was a problem hiding this comment.
if we can avoid having the *.onrender.com URL in this listing, that would be ideal. since it's a free-tier deployment, there are two hiccups:
- the cold-start time is noticeable to anyone trying it out (about 40 seconds when i tried
GET /supported) - as soon as you do upgrade or migrate to some other host/URL, this page will break
we can add the facilitator URL at a later time, if necessary. but for now, i'd rather let the Vellar docs carry that information for users until it's more "permanent."
|
|
||
| ::: | ||
|
|
||
| ### Community facilitators |
Contributor
There was a problem hiding this comment.
Suggested change
| ### Community facilitators | |
| ### Community Facilitators |
|
|
||
| #### Vellar Facilitator | ||
|
|
||
| [Vellar](https://github.com/Vellar-Wallet/vellar-facilitator) is an Apache-2.0 x402 facilitator that pairs the standard `/verify`, `/settle`, and `/supported` endpoints with a **Bazaar discovery layer**: when a payment settles and its payload carries the Bazaar discovery extension, the facilitator may add the resource to a searchable catalog, so sellers that use the extension are listed without a separate registration step. Cataloging is conditional and can be refused for invalid discovery data, or when the resource URL is already bound to a different recipient; settlement succeeds either way, and payments without the extension settle normally but are never cataloged. The catalog is also reachable by AI agents through an [MCP](https://modelcontextprotocol.io) discovery server (`src/mcp.ts` in the repository), which is a separate stdio process you run locally and point at the facilitator URL; the hosted instance does not expose an MCP endpoint itself. The facilitator sponsors the settlement transaction fee, so buyers do not need XLM to pay for the transaction itself. Classic Stellar accounts still maintain their own base and trustline reserves. |
Contributor
There was a problem hiding this comment.
this part could be trimmed down quite a bit. i think it's grown a bit as you were working through copilot reviews (which i very much appreciate!), but it's drifted into a bit in the long-winded direction. nothing here looks inaccurate, just a little hard to read.
ideally, something around 150-words-or-so might fit well alongside the other two facilitator entries on this page.
Contributor
There was a problem hiding this comment.
there's also some info that doesn't fit all that well in this docs repo
- the
Apache-2.0license doesn't need specifying here - the bolded
**Bazaar discovery layer:**leans a little "market-y" - pointing to
src/mcp.tsin your repo is a maintenance hazard that could bit us here if you refactor the codebase down the road.
Contributor
There was a problem hiding this comment.
maybe something like this could work well
Suggested change
| [Vellar](https://github.com/Vellar-Wallet/vellar-facilitator) is an Apache-2.0 x402 facilitator that pairs the standard `/verify`, `/settle`, and `/supported` endpoints with a **Bazaar discovery layer**: when a payment settles and its payload carries the Bazaar discovery extension, the facilitator may add the resource to a searchable catalog, so sellers that use the extension are listed without a separate registration step. Cataloging is conditional and can be refused for invalid discovery data, or when the resource URL is already bound to a different recipient; settlement succeeds either way, and payments without the extension settle normally but are never cataloged. The catalog is also reachable by AI agents through an [MCP](https://modelcontextprotocol.io) discovery server (`src/mcp.ts` in the repository), which is a separate stdio process you run locally and point at the facilitator URL; the hosted instance does not expose an MCP endpoint itself. The facilitator sponsors the settlement transaction fee, so buyers do not need XLM to pay for the transaction itself. Classic Stellar accounts still maintain their own base and trustline reserves. | |
| [Vellar](https://github.com/Vellar-Wallet/vellar-facilitator) serves the standard `/verify`, `/settle`, and `/supported` endpoints, and adds an optional Bazaar discovery layer: when a payment carries Vellar's discovery extension, the facilitator may also add that resource to a searchable catalog, so sellers are listed without registering separately. Cataloging is best-effort and never blocks settlement, and payments without the extension settle as normal. The catalog can also be queried by AI agents through an [MCP](https://modelcontextprotocol.io) discovery server, which you run yourself and point at a facilitator. Vellar sponsors the settlement transaction fee, though classic accounts still fund their own base and trustline reserves. |
- Remove hardcoded count from intro ("Two production...") in favour of
"The following options are available for Stellar:" so the sentence
stays accurate as the list grows
- Capitalise "Community Facilitators" per suggestion
- Replace the body paragraph with the suggested ~150-word version:
drops the Apache-2.0 licence mention, the bold Bazaar marketing
framing, and the src/mcp.ts file path (maintenance hazard)
- Remove the hosted onrender.com URL; the docs site carries it
- Simplify the note to the essentials: pre-production, no independent
audit yet, link to Vellar's security notes, free-tier cold-start
warning; drop the internal-review / contract-scope detail that
doesn't belong in the ecosystem listing
|
|
||
| :::note | ||
|
|
||
| Pre-production. Vellar has not yet undergone an independent external security audit. See [Vellar's security notes](https://docs.vellar.xyz) for the current review status. The hosted instance runs on a free tier, so the first request after an idle period can take up to a minute. |
Author
|
@ElliotFriend all requested changes are addressed in 5b5565b:
One deliberate departure: "Testnet only" became "Pre-production" because the facilitator went live on mainnet (stellar:pubnet) today, so "Testnet only" would now be inaccurate. Everything else follows your suggestions exactly. |
Copilot flagged that 'Pre-production' alone leaves readers unable to tell which networks the facilitator supports. Added 'available on Testnet and Mainnet' inline. The hosted URL remains omitted per ElliotFriend's explicit request.
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.
Suppressed comments (2)
Previously missed (1) — in code that hasn't changed since the last review.
docs/build/agentic-payments/x402/README.mdx:104
- Catalog insertion runs after a successful settlement, but this wording makes carrying the extension sound sufficient; a payment that fails or never reaches settlement is not cataloged. Please retain the settlement condition explicitly.
docs/build/agentic-payments/x402/README.mdx:111
- This contradicts the PR's testnet-only status and the documented release gate: there is no Mainnet instance yet, and the outstanding external audit blocks the Mainnet release. Saying the facilitator is available on Mainnet can direct readers to a service that is not deployed.
Pre-production; available on Testnet and Mainnet. Vellar has not yet undergone an independent external security audit. See [Vellar's security notes](https://docs.vellar.xyz) for the current review status. The hosted instance runs on a free tier, so the first request after an idle period can take up to a minute.
Copilot flagged that 'when a payment carries the extension' implies carrying it alone is sufficient. Settlement must succeed first; restored 'settles and carries' to make that explicit.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds Vellar to the x402 facilitators section under a new Community Facilitators subsection.
Vellar is a hosted x402 facilitator for Stellar with:
Live on Testnet and Mainnet: https://vellar-facilitator.onrender.com
GitHub: https://github.com/Vellar-Wallet/vellar-facilitator
Docs: https://docs.vellar.xyz
Status: pre-production. An external security audit has not yet been commissioned and is a hard blocker for a versioned Mainnet release tag; the Mainnet instance is running but not yet production-grade.
A note on placement
I added a new
### Community Facilitatorssubsection rather than a third entry alongside the Coinbase and Build on Stellar facilitators, because those two are production-grade and this one is pre-production. The "The following options are available for Stellar" sentence is deliberately left without a hardcoded count. The new subsection carries a line stating these are not maintained by SDF, so it should also serve any future community entries rather than being Vellar-specific.Filed as a draft originally; all review comments from ElliotFriend addressed in subsequent commits.