Let a plugin route declare a price, and have the host run the x402 flow using the site's own x402 configuration

[masonjames]

The problem

EmDash ships x402 for Astro pages through @emdash-cms/x402, but sandboxed plugins can't use it. That includes every plugin installed from the registry.

• A raw route response can only set the headers the host allows (ALLOWED_RESPONSE_HEADERS in packages/core/src/plugins/route-wire.ts). PAYMENT-REQUIRED and PAYMENT-RESPONSE aren't on that list, so a plugin route can't send an x402 challenge or a payment receipt.
• Allowing those response headers would let a plugin run its own x402 flow through ctx.http, with the network capability and the facilitator as an allowed host. But payment handling would stay plugin-managed: each plugin would verify and settle payments in sandboxed code and choose where the money goes. That's security-critical work, and it belongs to the host.

I'm building a paid-content plugin, Paid Access, that sells Markdown reads of individual posts to AI agents over x402. Its registry build can't serve the x402 route, so that route ships as a native Astro companion that site operators must install and configure separately.

Proposal

Let a plugin route declare a price, and have the host run the x402 flow using the site's own x402 configuration (payTo, network and facilitator):

1. The route returns a quote for the request: a price and description, or nothing if it's free.
2. The host sends the 402 with PAYMENT-REQUIRED. On the retry, it verifies the client's PAYMENT-SIGNATURE against that quote.
3. The handler runs with the verified payment on its context (payer, amount and network) and returns its response.

If the handler succeeded, the host settles the payment, adds PAYMENT-RESPONSE and sends the response.

The plugin never handles payment headers and never picks the recipient; the site owner's configuration does. The host settles only after the handler returns a successful response, so a request that throws or returns an error isn't charged.

A possible shape:

routes: {
	entry: pluginRoute({
		public: true,
		methods: ["GET"],
		response: "raw",
		payment: {
			// null means this request is free
			quote: async (routeCtx) => ({ price: "$0.01", description: "Markdown for one post" }),
		},
		handler: async (routeCtx) => {
			// routeCtx.payment holds the payment the host verified
			return pluginResponse({ status: 200, headers: { "content-type": "text/markdown" }, body });
		},
	}),
},

Alternatives

• Allow the two headers on raw routes, and let plugins call a facilitator through ctx.http. It's a smaller change, but every plugin reimplements payment handling and sets its own recipient.
• Keep x402 for native code only. Registry plugins would still need separately installed native code to expose x402-paid routes.

Questions

• Is a per-request quote the right shape, or would a fixed price per route be enough to start?
• How should a plugin learn the settlement result for its receipts? A payment:settled hook, or something on the route context?
• Should this depend on the site configuring @emdash-cms/x402, or should core own the facilitator client?

If this direction works, I'm happy to write the PR.