Discovery: MCP Registry server.json + x402 bazaar listing; Telegram contact

- server.json: remote MCP manifest (io.github.rotwang9000/seneschal-data),
  validated against registry.modelcontextprotocol.io. Ready to publish.
- x402.js: decorate every paid route with a bazaar discovery extension so
  the openx402 facilitator catalogues us in /discovery/resources on the
  next settlement. discoveryConfigForRouteKey() is pure + tested; the
  extension loads lazily with the rest of the x402 stack.
- /.well-known/x402: enrich service block with description, control_panel,
  stats, Telegram contact, and a products[] array (Private Watch first).
- README: lead with Private Watch + paid tiers; tools 9->18; tests 75->539;
  add panel row + MCP-Registry note; Discord -> Telegram (@OrknetP).
- docs/index.html: fair-use contact Discord -> Telegram.
- add @x402/extensions as an explicit dependency (was transitive).
- 539/539 tests green.

Author: S. K. Rotwang MMMMMMMMM

README.md

@@ -3,17 +3,32 @@
 [![ci](https://github.com/Rotwang9000/seneschal-data-api/actions/workflows/ci.yml/badge.svg)](https://github.com/Rotwang9000/seneschal-data-api/actions/workflows/ci.yml)
 [![license](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
-Free, public, read-only REST + [Model Context Protocol](https://modelcontextprotocol.io)
+Free, public REST + [Model Context Protocol](https://modelcontextprotocol.io)
 server exposing real-time and historical DeFi liquidation telemetry for
 Aave, Morpho, Spark and Compound on Ethereum mainnet, plus block-builder
 market share data from the operator's own slot-by-slot shadow recorder.
 
+Two paid tiers sit on top, both billed per call over
+[x402](https://docs.x402.org) micropayments (USDC on Base — no account, no
+API key):
+
+- **Private Watch** *(flagship)* — give us a Monero or Zcash **view key**
+  and a webhook URL; we watch the chain on our own full nodes and POST you
+  an HMAC-signed event for every inbound payment. Credit-metered
+  ($0.02/day + $0.005/call), so small receivers pay pennies and you never
+  run a node. Drive it from the API, the MCP tools, or the
+  [WalletConnect control panel](https://panel.seneschal.space).
+- **Premium data** — expected-value-ranked liquidation opportunities,
+  per-builder bid distributions, and Penny Oracle atomic single-fact
+  endpoints (DeFi + Monero/Zcash) from $0.001/call.
+
 ## Live endpoints
 
 | What                          | URL                              | Auth     |
 |-------------------------------|----------------------------------|----------|
 | REST API                      | `https://api.seneschal.space`    | None     |
 | MCP (Streamable HTTP)         | `https://mcp.seneschal.space`    | None     |
+| Control panel (Private Watch) | `https://panel.seneschal.space`  | Wallet   |
 | Docs                          | `https://docs.seneschal.space`   | -        |
 | Live stats dashboard          | `https://stats.seneschal.space`  | -        |
 
@@ -42,7 +57,13 @@ Add this to your MCP client config (e.g. `~/.cursor/mcp.json`):
 }
 ```
 
-Nine tools become available to your agent:
+This server is published to the official
+[MCP Registry](https://registry.modelcontextprotocol.io) as
+`io.github.rotwang9000/seneschal-data` (see [`server.json`](server.json)),
+so MCP-aware clients and aggregators can discover it automatically.
+
+Eighteen tools become available to your agent — free read tools, plus
+paid tools that hand back the exact URL + body to settle over x402:
 
 | Tool                                 | Purpose                                                              |
 |--------------------------------------|----------------------------------------------------------------------|
@@ -55,6 +76,15 @@ Nine tools become available to your agent:
 | `seneschal_builder_leaderboard`      | Ethereum builder market share (24h, 7d, 30d, all-time)               |
 | `seneschal_stats_overview`           | Aggregate snapshot powering the public dashboard, incl. operator activity (counts only — no profit fields) |
 | `seneschal_flashloan_providers`      | Curated catalogue of mainnet flash-loan providers, incl. LP-side commit-capital paths where applicable     |
+| `seneschal_paywall_info`             | Free metadata for the x402 paywall (network, recipient, per-call price)                                    |
+| `seneschal_premium_opportunities`    | EV-ranked at-risk borrowers with realised market intel *(x402, paid)*                                      |
+| `seneschal_premium_builder_stats`    | Per-builder bid distribution + hourly slot histogram for bundle pricing *(x402, paid)*                     |
+| `seneschal_q`                        | Penny Oracle dispatcher — atomic single facts across DeFi + Monero/Zcash, $0.001/call *(x402, paid)*       |
+| `seneschal_private_watch_info`       | Free metadata for Private Watch: meter, supported chains, NFPT upstream health, security notes             |
+| `seneschal_private_watch_create`     | Subscribe an XMR/ZEC view key to webhook payment monitoring *(x402, paid)*                                 |
+| `seneschal_private_watch_topup`      | URL + body to top up an existing watch's credit ($0.10 / $1 / $5 tiers)                                    |
+| `seneschal_private_watch_historical` | One-off paid scan returning spendable + spent notes for a view key *(x402, paid; key never persists)*      |
+| `seneschal_private_watch_derive_viewkey` | Free, rate-limited Zcash UFVK derivation from a BIP-39 mnemonic (with a loud security warning)         |
 
 ## REST endpoints
 
@@ -123,11 +153,13 @@ producing the same shapes you can point this server at it.
 npm test
 ```
 
-75 jest tests covering the query layer (in-memory SQLite fixtures), the
-Fastify REST routes (via `fastify.inject`), and the MCP server (both
+539 jest tests covering the query layer (in-memory SQLite fixtures), the
+Fastify REST routes (via `fastify.inject`), the MCP server (both
 in-process via `InMemoryTransport` and end-to-end via
-`StreamableHTTPClientTransport`). Plus `test/live-smoke.mjs` which
-exercises the live `mcp.seneschal.space` endpoint over Streamable HTTP.
+`StreamableHTTPClientTransport`), the x402 paywall + bazaar-discovery
+wiring, the Private Watch credit meter / poller / surge pricing, and the
+ops watchdog. Plus `test/live-smoke.mjs` which exercises the live
+`mcp.seneschal.space` endpoint over Streamable HTTP.
 
 ## Architecture
 
@@ -190,6 +222,7 @@ budget a session before opening a paid request.
 - **Direct tips**: ETH / BTC addresses are surfaced on
   [stats.seneschal.space](https://stats.seneschal.space) once the
   operator sets `SENESCHAL_DONATE_ETH` / `SENESCHAL_DONATE_BTC`.
+- **Questions / allow-list bumps**: Telegram [`@OrknetP`](https://t.me/OrknetP).
 
 Seneschal runs on a single Helsinki box; every cent helps keep it
 online.
@@ -202,5 +235,5 @@ MIT — see [LICENSE](LICENSE).
 
 Seneschal is a single-operator Ethereum block builder and searcher
 running an `rbuilder` fork from a co-located server in Helsinki.
-Builder on-chain extra_data is `Seneschal/0.1`. Contact `@Rotwang9000`
-on Discord.
+Builder on-chain extra_data is `Seneschal/0.1`. Contact
+[`@OrknetP`](https://t.me/OrknetP) on Telegram (checked periodically).

docs/index.html

@@ -880,7 +880,7 @@ <h2>Data freshness &amp; coverage</h2>
 
 <h2>Limits, terms, fair use</h2>
 <ul>
-<li>120 req/min per IP, soft. Heavy users should ask for an allow-list bump on Discord.</li>
+<li>120 req/min per IP, soft. Heavy users should ask for an allow-list bump on Telegram (<a href="https://t.me/OrknetP"><code>@OrknetP</code></a>).</li>
 <li>No SLA. This is a free best-effort service. Expect occasional restarts.</li>
 <li>Use of the data must not violate any privacy or legal restrictions in your jurisdiction. We surface only on-chain data and our own observations.</li>
 <li>Crediting Seneschal (<code>https://seneschal.space</code>) in derived work is appreciated but not required.</li>

package.json

@@ -20,6 +20,7 @@
 		"@modelcontextprotocol/sdk": "^1.29.0",
 		"@x402/core": "^2.12.0",
 		"@x402/evm": "^2.12.0",
+		"@x402/extensions": "^2.12.0",
 		"@x402/fastify": "^2.12.0",
 		"@x402/paywall": "^2.12.0",
 		"better-sqlite3": "^12.10.0",

server.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.rotwang9000/seneschal-data",
+  "title": "Seneschal Data",
+  "description": "Live DeFi liquidation, Ethereum builder & Monero/Zcash data over MCP. Free, no key; x402 premium.",
+  "version": "0.1.0",
+  "websiteUrl": "https://seneschal.space",
+  "repository": {
+    "url": "https://github.com/Rotwang9000/seneschal-data-api",
+    "source": "github"
+  },
+  "remotes": [
+    {
+      "type": "streamable-http",
+      "url": "https://mcp.seneschal.space/"
+    }
+  ]
+}

src/rest-server.js

@@ -1100,10 +1100,29 @@ export async function buildApp(options = {}) {
 			...paywallSummary,
 			service: {
 				name: 'Seneschal Data API',
+				description: 'On-chain DeFi liquidation + Ethereum builder telemetry and Monero/Zcash payment-watching, payable per call over x402. Free read tier, no API key.',
 				homepage: 'https://seneschal.space',
-				docs: 'https://docs.seneschal.space/#premium-tier-x402',
+				docs: 'https://docs.seneschal.space',
 				api_root: 'https://api.seneschal.space',
-				mcp: 'https://mcp.seneschal.space'
+				mcp: 'https://mcp.seneschal.space',
+				control_panel: 'https://panel.seneschal.space',
+				stats: 'https://stats.seneschal.space',
+				contact: 'https://t.me/OrknetP',
+				products: [
+					{
+						name: 'Private Watch',
+						summary: 'Watch a Monero or Zcash view key for inbound payments and receive an HMAC-signed webhook on each one. Credit-metered (per-day + per-call), no node to run.',
+						start: 'POST /v1/private/watch',
+						info: 'https://api.seneschal.space/v1/private/info',
+						panel: 'https://panel.seneschal.space'
+					},
+					{
+						name: 'DeFi + builder data',
+						summary: 'Real-time at-risk borrowers across Aave/Morpho/Spark/Compound, Ethereum builder market share, and Monero/Zcash chain facts. Free read tier; x402 premium feeds + Penny Oracle atomic facts.',
+						start: 'GET /v1/premium/opportunities',
+						info: 'https://api.seneschal.space/v1/paywall'
+					}
+				]
 			}
 		};
 	});

src/x402.js

@@ -195,6 +195,25 @@ function envKeyToCfg(envKey) {
 	return parts.map((p, i) => i === 0 ? p : p.charAt(0).toUpperCase() + p.slice(1)).join('');
 }
 
+/**
+ * Map a route key ("METHOD /path") to the minimal bazaar-discovery
+ * config we hand `declareDiscoveryExtension`. Body methods need an
+ * explicit `bodyType` (that's how the helper discriminates body vs
+ * query routes); query methods need nothing. We deliberately keep the
+ * declaration minimal — the route's own `description` + `mimeType`
+ * already ride along in the catalog entry, and the HTTP method is
+ * enriched at settlement time by `bazaarResourceServerExtension`, so
+ * there's nothing to drift out of sync here.
+ *
+ * Pure + exported so the wiring is unit-testable without loading the
+ * x402 payment stack.
+ */
+export function discoveryConfigForRouteKey(routeKey) {
+	const method = String(routeKey).trim().split(/\s+/u, 1)[0].toUpperCase();
+	const BODY_METHODS = new Set(['POST', 'PUT', 'PATCH']);
+	return BODY_METHODS.has(method) ? { bodyType: 'json' } : {};
+}
+
 function assertPrice(price, name) {
 	// Accept either Money strings ("$0.05") or atomic-unit strings
 	// ("50000" = 0.05 USDC at 6 decimals). The facilitator handles
@@ -226,13 +245,33 @@ export async function registerX402(app, x402Cfg) {
 	// premium URL in their browser we'd rather they see the structured
 	// 402 JSON than an opinionated wallet-connect dialog they can't
 	// use anyway.
-	const [{ paymentMiddlewareFromConfig }, { HTTPFacilitatorClient }, { ExactEvmScheme }] = await Promise.all([
+	const [{ paymentMiddlewareFromConfig }, { HTTPFacilitatorClient }, { ExactEvmScheme }, { declareDiscoveryExtension }] = await Promise.all([
 		import('@x402/fastify'),
 		import('@x402/core/server'),
-		import('@x402/evm/exact/server')
+		import('@x402/evm/exact/server'),
+		// Bazaar discovery: lets the facilitator we already use
+		// (openx402) catalogue our paid routes in its public
+		// `/discovery/resources` index once each route has settled at
+		// least one payment. Loaded lazily with the rest of the x402
+		// stack so the API still boots clean when the paywall is off.
+		import('@x402/extensions/bazaar')
 	]);
 	const facilitatorClient = new HTTPFacilitatorClient({ url: x402Cfg.facilitatorUrl });
 	const schemes = [{ network: x402Cfg.network, server: new ExactEvmScheme() }];
+	// Decorate each route with a bazaar discovery extension. Additive
+	// metadata only — @x402/fastify detects `extensions.bazaar`, enriches
+	// the HTTP method at request time, and the facilitator soft-drops
+	// anything malformed, so this can't break verification/settlement.
+	const routesWithDiscovery = {};
+	for (const [key, routeCfg] of Object.entries(x402Cfg.routes)) {
+		routesWithDiscovery[key] = {
+			...routeCfg,
+			extensions: {
+				...(routeCfg.extensions ?? {}),
+				...declareDiscoveryExtension(discoveryConfigForRouteKey(key))
+			}
+		};
+	}
 	// `syncFacilitatorOnStart: true` is required — it fetches the
 	// /supported manifest from the facilitator so the resource server
 	// knows which (scheme, network) tuples it can issue
@@ -241,7 +280,7 @@ export async function registerX402(app, x402Cfg) {
 	// exact on eip155:8453".
 	paymentMiddlewareFromConfig(
 		app,
-		x402Cfg.routes,
+		routesWithDiscovery,
 		facilitatorClient,
 		schemes,
 		/* paywallConfig */ undefined,

test/rest-server.test.js

@@ -533,6 +533,14 @@ describe('paywall surface (x402 enabled, in-process)', () => {
 		expect(body.service.name).toMatch(/Seneschal/);
 		expect(body.service.homepage).toBe('https://seneschal.space');
 		expect(body.service.api_root).toBe('https://api.seneschal.space');
+		// Discovery surface advertises the control panel + Telegram
+		// contact (operator no longer monitors Discord) and lists the
+		// flagship Private Watch product first.
+		expect(body.service.control_panel).toBe('https://panel.seneschal.space');
+		expect(body.service.contact).toBe('https://t.me/OrknetP');
+		expect(Array.isArray(body.service.products)).toBe(true);
+		expect(body.service.products[0].name).toBe('Private Watch');
+		expect(body.service.products[0].start).toBe('POST /v1/private/watch');
 		expect(body.routes.length).toBe(1);
 	});
 

test/x402.test.js

@@ -4,7 +4,9 @@
 // REST integration tests.
 
 import { describe, test, expect } from '@jest/globals';
-import { buildX402Config, describePaywall, PREMIUM_ROUTES } from '../src/x402.js';
+import { buildX402Config, describePaywall, discoveryConfigForRouteKey, PREMIUM_ROUTES } from '../src/x402.js';
+import { declareDiscoveryExtension, validateDiscoveryExtension } from '@x402/extensions/bazaar';
+import { checkIfBazaarNeeded } from '@x402/core/server';
 
 const PAY_TO = '0x1234567890abcdef1234567890abcdef12345678';
 
@@ -135,3 +137,47 @@ describe('describePaywall', () => {
 		expect(typeof route.description).toBe('string');
 	});
 });
+
+describe('discoveryConfigForRouteKey (bazaar discovery wiring)', () => {
+	test('query (GET/HEAD/DELETE) routes get an empty config', () => {
+		expect(discoveryConfigForRouteKey('GET /v1/q/xmr/height')).toEqual({});
+		expect(discoveryConfigForRouteKey('GET /v1/premium/opportunities')).toEqual({});
+	});
+
+	test('body methods (POST/PUT/PATCH) declare bodyType json', () => {
+		expect(discoveryConfigForRouteKey('POST /v1/private/watch')).toEqual({ bodyType: 'json' });
+		expect(discoveryConfigForRouteKey('PUT /x')).toEqual({ bodyType: 'json' });
+		expect(discoveryConfigForRouteKey('PATCH /x')).toEqual({ bodyType: 'json' });
+	});
+
+	test('is tolerant of extra whitespace and case in the route key', () => {
+		expect(discoveryConfigForRouteKey('post   /v1/private/topup')).toEqual({ bodyType: 'json' });
+		expect(discoveryConfigForRouteKey('  get /v1/q/zec/height ')).toEqual({});
+	});
+
+	// The decoration logic mirrors registerX402: produce a bazaar
+	// extension per route from the pure config. We assert the result is
+	// shaped such that (a) the middleware will detect it and (b) it
+	// validates once the HTTP method is enriched at settlement time —
+	// exactly what bazaarResourceServerExtension does on the live path.
+	test('every PREMIUM_ROUTES key yields a bazaar extension the middleware will catalogue', () => {
+		const cfg = buildX402Config({ cfg: baseCfg(), env: {} });
+		const routesWithDiscovery = {};
+		for (const [key, routeCfg] of Object.entries(cfg.routes)) {
+			routesWithDiscovery[key] = {
+				...routeCfg,
+				extensions: { ...declareDiscoveryExtension(discoveryConfigForRouteKey(key)) }
+			};
+		}
+		expect(checkIfBazaarNeeded(routesWithDiscovery)).toBe(true);
+
+		for (const [key, routeCfg] of Object.entries(routesWithDiscovery)) {
+			const bazaar = routeCfg.extensions.bazaar;
+			expect(bazaar).toBeDefined();
+			// Enrich the method the way the runtime server extension does,
+			// then it must pass the facilitator's schema validation.
+			bazaar.info.input.method = key.split(' ', 1)[0];
+			expect(validateDiscoveryExtension(bazaar)).toEqual({ valid: true });
+		}
+	});
+});