Add agent discovery support for @emdash-cms/x402 so EmDash sites can be found and fetched by AI agents

[fmhall]

Summary

I’d like EmDash’s @emdash-cms/x402 integration to support agent-friendly discovery metadata so AI agents can find paid resources on an EmDash-powered site, understand how to call them, and pay automatically when appropriate.

The core idea is to let a site expose a machine-readable discovery document, an openapi.json, which fits the agent discovery standard from Merit Systems and used by agents through AgentCash. This discovery standard was built in collaboration with Coinbase and Stripe/Tempo. Full spec can be found here.

It's a standard openapi.json, but includes a few extra fields specific to agent discovery and payment.

EmDash is well-positioned for this

EmDash already has strong CMS and content modeling primitives, and @emdash-cms/x402 already handles enforcement. Discovery through the bazaar is supported, but insufficient for agents to find and pay for resources programmatically without running their own x402 infrastructure.

Adding discovery is a natural extension:

• enforcement already exists
• the missing piece is discoverability
• OpenAPI is already a familiar ecosystem standard

Why now

Agents are increasingly using structured API discovery instead of ad hoc browsing. EmDash already has the enforcement half of the story through x402. Adding discovery closes the loop and makes the feature materially useful in real agent workflows.

[fmhall]

Would appreciate any feedback here, I've also started work on a draft PR I can share if interest!

[ascorbic]

Good idea! Happy to accept a PR for this

[masonjames]

@fmhall would you mind sharing your draft PR? Would love to take a look. Thank you!

[danielmlr]

@fmhall @masonjames — is anyone still on this? The draft PR mentioned back in April was never opened, so unless someone is mid-flight I would like to pick it up.

Before writing any code, one design question, because it decides the shape of the PR.

The AgentCash spec wants GET /openapi.json at the site root with an x-payment-info block carrying a concrete price on every paid operation. Getting the route list is the easy half: astro:routes:resolved hands the integration every project route at build time. The prices are the problem.

Enforcement in @emdash-cms/x402 is imperative, in page frontmatter:

const result = await x402.enforce(Astro.request, { price: entry.data.price || "$0.01" });

That is the documented per-page pricing pattern, and it reads the price off a CMS field per entry. So nothing outside the rendered page knows which routes call enforce() at all, or what they charge. X402Config carries payTo, network and defaultPrice, and has no notion of routes.

Three ways out:

1. A declarative discovery block in the integration config. The site author lists paid routes with prices and schemas; the integration generates the document from that and validates the declared patterns against the resolved route list, so a typo or a deleted page fails loudly instead of quietly publishing a wrong document. Per-entry pricing maps onto the spec's price.mode: "dynamic" with min/max. Cost: the price lives in two places and can drift from the enforce() call.
2. The same, plus enforce() falling back to the price declared for the matched route when no explicit price is passed. That removes the drift and makes the config the single source of truth, at the cost of touching the enforcement path.
3. Generating paths from CMS content at request time — enumerate published entries in the paid collections, one operation each with its real price. Most accurate, but it puts a query on a public route and couples x402 to emdash, which today depends only on @x402/*.

I lean towards 1 for this PR: additive, contained to packages/x402, enforcement untouched — with 2 as a follow-up if you want it. If you would rather have 2 in one go, or think 3 is the right target, say so and I will build that instead.

Two smaller points while I am asking:

• I would have the integration inject the route at /openapi.json, with the path configurable and the whole thing disableable, since a site may already serve its own. Separate from the existing /_emdash/api/openapi.json, which describes the CMS admin API, sends Cache-Control: private, no-store, and sits on a path the spec does not look at.
• The spec is written for JSON APIs: it expects an input and an output schema per operation, and the registration check rejects operations that lack them. A paid EmDash route is usually an HTML page. I would emit those as GET operations with a text/html response and the path parameters as input, but the spec text does not say whether the AgentCash validator accepts an HTML operation. If you know of a site already registered that way, that settles it.

[danielmlr]

Follow-up, because I checked the last point myself instead of waiting. Everything below was run against @agentcash/discovery@1.7.5, the validator the AgentCash docs point to for self-checks, with a local server that mirrors the @x402/core calls in packages/x402/src/enforcer.ts.

HTML operations validate clean. A document with GET /posts/{slug} (paid, price.mode: "dynamic") and GET /about (free), both returning text/html, comes through with zero warnings. The validator reports the route, the price range and the protocol correctly. So my earlier worry about per-operation schemas was misplaced: the schema requirement exists, but it sits on the 402 response, not on the OpenAPI document.

That is where EmDash currently fails. The 402 that enforcer.ts builds carries x402Version, error, resource and accepts, but no extensions. The validator expects extensions.bazaar.schema.properties.input.properties.{body|queryParams} and extensions.bazaar.schema.properties.output.properties.example, and reports SCHEMA_INPUT_MISSING and SCHEMA_OUTPUT_MISSING as errors when they are absent. Adding them makes the run warning-free. The fix is additive: createPaymentRequiredResponse takes extensions as its fourth argument and enforcer.ts passes three today, so this is an optional field on EnforceOptions threaded through. One wrinkle: the extractor knows body and queryParams only, so a route whose sole input is a path segment has to declare it under queryParams.

The npm package ships a spec that differs from the website. docs/SPECIFICATION.md in the package: ownership proofs live in x-agentcash-provenance, not x-discovery; info.x-guidance is recommended, not required; SIWX is marked with x-agentcash-auth-kind: "siwx" on the security scheme, and a scheme literally named siwx is compatibility only; every operation needs summary or description, an explicit security ([] for none) and responses. I will build against the package, since that is what the validator enforces.

This moves the design question a little. If the 402 has to carry extensions.bazaar for a site to register at all, the PR touches the enforcement path anyway, additively. That makes option 2 (declared route prices as the fallback inside enforce()) less of a leap than I made it sound. I still lean towards option 1 plus the 402 extension as the first PR, with option 2 as a follow-up if you want it. Happy to go either way.