feat(x402): pay-per-call premium tier on /v1/premium/* + MCP

Adds an honest revenue mechanism for the data API: per-request USDC
payment via the x402 protocol on Base mainnet. The paywall is off by
default (X402_RECIPIENT_ADDRESS unset → 503 paywall_not_configured) so
the public service keeps shipping the free surface untouched. When the
operator sets a recipient, unsigned requests get HTTP 402 + machine
readable PaymentRequirements; the @x402/fastify middleware delegates
verification + EIP-3009 settlement to the configured facilitator
(default https://x402.org/facilitator).

First paid endpoint: GET /v1/premium/opportunities. Returns the
uncapped at-risk borrower catalogue joined with realised 7d market
intel (top liquidators, win rate per (collateral,debt) pair, our own
attempt outcomes per Morpho market) and ranked by expected value
(debt × bonus × historical win-rate). Pure SQL over data we already
collect; no live RPC.

MCP surface gains two tools mirrored from the REST routes:
- seneschal_paywall_info (free, exposes price/recipient/network)
- seneschal_premium_opportunities (returns the feed; MCP transports
  don't yet negotiate payment, so this stays free until the spec
  lands a transport-level 402)

Dashboard + landing page surface the premium tier when configured.
.github/FUNDING.yml adds GitHub Sponsors visibility + a custom link
to /v1/paywall.

Tests: 108 passing (+33 new). Unit-tests cover config validation,
describePaywall projection, market-intel aggregation, EV ranking,
parameter validation, and REST 402/503 wire-up.

Author: Rotwang9000

.github/FUNDING.yml

@@ -0,0 +1,12 @@
+# Configure the Sponsor button at the top of the GitHub repo. The
+# data-api lives on a single Helsinki box and is free to use; tips
+# keep it lit. Per-call agent payments via x402 are the preferred
+# revenue path — see /v1/paywall on the live service for the
+# machine-readable price + recipient.
+
+github: [Rotwang9000]
+# Add the operator's ENS / 0x address(es) below once a dedicated
+# donation wallet is provisioned. We intentionally don't list the
+# bot's executor wallets here because those keys are hot.
+custom:
+  - 'https://api.seneschal.space/v1/paywall'

README.md

@@ -150,6 +150,50 @@ Shared design rule: both REST and MCP layers are *thin* wrappers around
 `queries.js`. Any new endpoint goes in `queries.js` first (with tests),
 then both wrappers in the same commit.
 
+## Premium tier (x402 paywall)
+
+`src/queries-premium.js` plus `src/x402.js` add per-call payment to a
+small family of `/v1/premium/*` endpoints (and `seneschal_premium_*`
+MCP tools). The paywall is off unless the operator sets
+`X402_RECIPIENT_ADDRESS`. Once set, unsigned requests get HTTP 402 with
+machine-readable payment requirements, and an
+[x402 facilitator](https://docs.x402.org) settles a signed
+EIP-3009 `transferWithAuthorization` for USDC on Base mainnet.
+
+### Configure
+
+| Env var                    | Default                          | Notes                                                                  |
+| -------------------------- | -------------------------------- | ---------------------------------------------------------------------- |
+| `X402_RECIPIENT_ADDRESS`   | (empty — paywall off)            | Recipient wallet on the chosen network. 0x-prefixed 20-byte hex.       |
+| `X402_NETWORK`             | `eip155:8453` (Base mainnet)     | Any CAIP-2 EVM network the facilitator supports.                       |
+| `X402_FACILITATOR_URL`     | `https://x402.org/facilitator`   | Use a production facilitator for mainnet (see x402.org/ecosystem).     |
+| `X402_FEED_PRICE`          | `$0.05`                          | Money-formatted (`$0.05`) or atomic units (`50000`).                   |
+| `X402_PAYWALL_DESCRIPTION` | …                                | Shown on `/`, `/v1/paywall`, and the stats dashboard.                  |
+| `X402_MAX_TIMEOUT_SECONDS` | `120`                            | Maximum settlement window per call.                                    |
+
+Free metadata endpoint (zero cost, no signature required):
+
+```
+curl https://api.seneschal.space/v1/paywall
+```
+
+returns the live network/recipient/price/route table so agents can
+budget a session before opening a paid request.
+
+## Support
+
+- **Per-call payments** (preferred for agents): pay $0.05 USDC on Base
+  to call `GET /v1/premium/opportunities`. See `/v1/paywall` for the
+  live recipient + rails.
+- **GitHub Sponsors**: the Sponsor button at the top of the repo
+  (`.github/FUNDING.yml`).
+- **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`.
+
+Seneschal runs on a single Helsinki box; every cent helps keep it
+online.
+
 ## License
 
 MIT — see [LICENSE](LICENSE).

docs/landing.html

@@ -47,6 +47,22 @@ <h2>For everyone else: free liquidation &amp; builder data</h2>
 <a href="https://mcp.seneschal.space/health">MCP <code>/health</code></a>
 </div>
 
+<h2>For agents: premium feed via x402</h2>
+<p>
+A small per-call USDC fee on Base unlocks
+<code>/v1/premium/opportunities</code>: the uncapped at-risk catalogue
+joined with realised 7-day market intel (top liquidators, win rate,
+our own attempt outcomes per market), pre-ranked by expected value.
+Standard x402 paywall &mdash; signed
+<code>transferWithAuthorization</code>, settlement by an x402
+facilitator, no API keys.
+</p>
+<div class="row">
+<a href="https://api.seneschal.space/v1/paywall">Paywall metadata</a>
+<a href="https://docs.x402.org">x402 spec</a>
+<a href="https://api.seneschal.space/v1/premium/opportunities">Premium endpoint</a>
+</div>
+
 <p class=muted>
 Contact: Rotwang9000 on Discord.
 </p>

docs/stats.html

@@ -261,6 +261,13 @@ <h2>Recent on-chain liquidations (last 24 h)</h2>
 		</div>
 	</div>
 
+	<!-- Premium tier (x402 paywall) -->
+	<div id="premium-panel" class="panel span-12" style="display:none">
+		<h2>Premium tier — pay-per-call</h2>
+		<p id="premium-blurb" style="color: var(--muted); margin-top: 0"></p>
+		<div id="premium-details" style="display:flex; flex-wrap: wrap; gap: 1em; margin-top: 0.8em; font-size: 0.95em"></div>
+	</div>
+
 	<!-- Support development -->
 	<div id="support-panel" class="panel span-12" style="display:none">
 		<h2>Support development</h2>
@@ -580,6 +587,41 @@ <h2>Support development</h2>
 	`).join('');
 }
 
+function renderPremium(d) {
+	const panel = document.getElementById('premium-panel');
+	const p = d.premium_tier;
+	if (!p || !p.enabled) {
+		panel.style.display = 'none';
+		return;
+	}
+	panel.style.display = '';
+	document.getElementById('premium-blurb').textContent = p.blurb
+		|| 'Pay-per-call x402 micropayment unlocks the uncapped opportunity feed plus realised market intel.';
+	const cells = [];
+	cells.push(`
+		<div class="tile" style="flex:1; min-width: 240px">
+			<div class="kpi-label">Price per call</div>
+			<div style="font-size: 1.4em; font-weight: 600">${escapeHtml(p.price_per_call || '$0.05')}</div>
+			<div class="kpi-sub">USDC on ${escapeHtml((p.network || 'eip155:8453').replace('eip155:8453', 'Base mainnet'))}</div>
+		</div>
+	`);
+	cells.push(`
+		<div class="tile" style="flex:2; min-width: 320px">
+			<div class="kpi-label">Endpoint</div>
+			<div style="word-break: break-all; font-family: monospace; font-size: 0.9em">GET ${escapeHtml(p.endpoint || '')}</div>
+			<div class="kpi-sub">x402 spec: <a href="${escapeHtml(p.docs || 'https://docs.x402.org')}" target="_blank" rel="noopener">docs.x402.org</a> · MCP tool: <code>${escapeHtml(p.mcp_tool || 'seneschal_premium_opportunities')}</code></div>
+		</div>
+	`);
+	cells.push(`
+		<div class="tile" style="flex:1; min-width: 240px">
+			<div class="kpi-label">Recipient</div>
+			<div style="word-break: break-all; font-family: monospace; font-size: 0.88em">${escapeHtml(p.payTo || '')}</div>
+			<div class="kpi-sub">EIP-3009 transferWithAuthorization — gasless for the payer.</div>
+		</div>
+	`);
+	document.getElementById('premium-details').innerHTML = cells.join('');
+}
+
 function renderSupport(d) {
 	const panel = document.getElementById('support-panel');
 	const s = d.support;
@@ -640,6 +682,7 @@ <h2>Support development</h2>
 		renderTopAtRisk(d);
 		renderLiqDaily(d);
 		renderRecentLiq(d);
+		renderPremium(d);
 		renderSupport(d);
 		clearError();
 		const ts = new Date(d.as_of_ms);