Bazaar: seller-side discovery metadata helpers (and list Lens's own endpoints)

[Miracle656]

Context

From §3.2 of the RFP:

"Seller side helpers so a resource server can declare discovery metadata correctly, including per parameter descriptions that make an endpoint legible to an agent, with minimal boilerplate."

And from §3.6, the UX bar:

"A developer should get from docs to a paid, discoverable endpoint appearing in the Bazaar in well under an hour."

Why per-parameter descriptions matter more than they sound

The buyer is software. An agent choosing between two price feeds cannot open your docs — it has only what the listing declares. An endpoint described as GET /price/:assetA/:assetB is nearly useless to it; one that declares what assetA accepts, what the response contains, and what it costs is selectable. Metadata quality is what ranking in #129 has to rank on — poor descriptions cap search quality no matter how good the retrieval is.

Scope

Helpers a resource server can use to declare discovery metadata with minimal ceremony:

• Declare a resource, its parameters with descriptions, its pricing and its network
• Emit the discovery extension correctly on the payment path so automatic cataloging (Bazaar: automatic cataloging from the discovery extension #130) picks it up
• Validate locally, before anything is sent, so a seller finds out their metadata is malformed at development time rather than from an EXTENSION-RESPONSES header in production
• Cover both HTTP endpoints and MCP tools

Dogfood it

Lens is itself an x402 seller — src/middleware/x402.ts gates /price, /pools, /candles, /ws. Use these helpers to make Lens's own endpoints discoverable. If declaring metadata for our own price feed is awkward, it will be awkward for everyone else, and we will find that out before shipping rather than after. That also makes Lens the first listing in its own Bazaar, which is a reasonable demo in its own right.

Acceptance criteria

• A resource server can declare a discoverable, priced endpoint in a few lines
• Per-parameter descriptions are first-class, not an afterthought
• Local validation catches malformed metadata before it is sent
• Both HTTP and MCP resource types supported
• Lens's own gated routes are declared using it, and appear in the catalog
• A developer following the README gets from nothing to a listed endpoint in well under an hour — say in the PR how long it actually took someone who had not seen it before

Drips Wave · Complexity: Medium · 150 points

---

Required: Before submitting, join the contributor Telegram so your work can be tracked and counted toward the Stellar Wave: https://t.me/+fxHXq8f1SwlkZDBk

[Dan-tolu]

@Dan-tolu has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

I'd love to work on this. I understand the requirements and can handle the implementation.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Dan-tolu to this issue.

[testimonyblockchain]

@Nobody426 has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

Hello maintainer pls assign this issue to me

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Nobody426 to this issue.

[Isihaq123]

@Isihaq123 has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

i will like to work on this issues, please

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Isihaq123 to this issue.

[DevTobis]

@DevTobis has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

Hi, I would like to work on this issue. I will build the seller-side discovery metadata helpers that let a resource server declare a discoverable priced endpoint in a few lines, with per-parameter descriptions as a first-class field rather than an optional extra, covering both HTTP endpoints and MCP tools and emitting the discovery extension correctly on the payment path so automatic cataloging in issue 130 picks it up without additional configuration. I will add local validation that catches malformed metadata at development time with a clear error message so sellers find out before anything is sent rather than from a cryptic header in production, and write a README that gets a developer from nothing to a listed endpoint in well under an hour. I will dogfood the helpers by declaring Lens's own gated routes including /price, /pools, /candles, and /ws using them so Lens becomes the first listing in its own Bazaar, and I will note the actual time it took someone unfamiliar with the code to get listed end to end in the PR description. Can I be assigned?

ℹ️ Repo Maintainers: To accept this application, review their application or assign @DevTobis to this issue.