x402: settle through Coinbase CDP facilitator when CDP keys present

S. K. Rotwang MMMMMMMMM · S. K. Rotwang MMMMMMMMM · commit 53d5a226440e · 2026-05-28T20:26:18.000Z
Route settlement through Coinbase's hosted x402 facilitator whenever
COINBASE_API_KEY/SECRET (or X402_CDP_*/CDP_*) are set, which lists the
service in the Coinbase x402 Bazaar and gives a 1k/month free
settlement tier. No business/KYB verification required to be a seller
(verified live against the CDP /supported endpoint: exact@base ok).

- config: x402CdpApiKeyId/Secret with COINBASE_*/CDP_* fallbacks
- x402: facilitator-mode selection (cdp|url) + shared
  createFacilitatorClient() used by both the static paywall and the
  dynamic custom top-up, so a signed challenge can't be verified
  against the wrong facilitator. Credentials are read at dispatch
  time and never stored on the public describePaywall surface.
- describePaywall exposes facilitator_mode
- docs (privacy/terms/index/landing/panel) + README re-point to
  Coinbase's facilitator (GDPR processor accuracy)
- +5 tests (544 green)
diff --git a/README.md b/README.md
@@ -198,7 +198,8 @@ EIP-3009 `transferWithAuthorization` for USDC on Base mainnet.
 | -------------------------- | -------------------------------- | ---------------------------------------------------------------------- |
 | `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).     |
+| `COINBASE_API_KEY` + `COINBASE_API_SECRET` | (empty) | **Recommended.** A [CDP API key](https://docs.cdp.coinbase.com/x402/quickstart-for-sellers). When both are set, settlement routes through Coinbase's hosted facilitator (`api.cdp.coinbase.com/platform/v2/x402`) and the service is auto-listed in the **Coinbase x402 Bazaar**. No business/KYB verification needed; 1k free settlements/month. Accepts `X402_CDP_API_KEY_ID` / `CDP_API_KEY_ID` aliases. |
+| `X402_FACILITATOR_URL`     | `https://facilitator.openx402.ai` | Fallback facilitator used only when no CDP credentials are set.        |
 | `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.                                    |
diff --git a/docs/index.html b/docs/index.html
@@ -681,18 +681,20 @@ <h3 id="penny-oracle">Penny Oracle — /v1/q/* atomic-fact endpoints</h3>
 <code>Payment-Required</code> header carrying machine-readable
 <code>PaymentRequirements</code>; the client signs an EIP-3009
 <code>transferWithAuthorization</code> off-chain and retries with a
-<code>X-PAYMENT</code> header. We delegate verify + settle to the
-<a href="https://facilitator.openx402.ai">openx402.ai</a> facilitator,
-which broadcasts the EIP-3009 transfer on Base. No API keys, no
-subscriptions, no gas for the payer — the facilitator pays the gas
-and stays solvent from a small spread on the underlying USDC.
+<code>X-PAYMENT</code> header. We delegate verify + settle to
+<a href="https://docs.cdp.coinbase.com/x402/welcome">Coinbase&rsquo;s CDP</a>
+facilitator, which broadcasts the EIP-3009 transfer on Base. No API
+keys for the payer, no subscriptions, no gas for the payer — the
+facilitator pays the gas. (Settling through Coinbase also lists the
+service in the Coinbase x402 Bazaar.)
 </p>
 <p>
 Free metadata endpoint for budgeting before any paid call:
 </p>
 <pre><code>curl https://api.seneschal.space/v1/paywall
 # → {"protocol":"x402","network":"eip155:8453",
-#    "facilitator":"https://facilitator.openx402.ai",
+#    "facilitator":"https://api.cdp.coinbase.com/platform/v2/x402",
+#    "facilitator_mode":"cdp",
 #    "payTo":"0x46Ba634261566CF242c853d1f49511f9268ba674",
 #    "scheme":"exact (EIP-3009 transferWithAuthorization)",
 #    "routes":[{"endpoint":"GET /v1/premium/opportunities","price":"$0.05",...},
diff --git a/docs/landing.html b/docs/landing.html
@@ -407,7 +407,7 @@ <h2>Other premium endpoints (x402 micropayments)</h2>
 <p>
 Pay-per-call endpoints on Base mainnet, settled in USDC via the x402
 protocol &mdash; no API keys, no subscriptions, no gas for the payer
-(the <a href="https://facilitator.openx402.ai">openx402.ai</a>
+(<a href="https://docs.cdp.coinbase.com/x402/welcome">Coinbase&rsquo;s CDP</a>
 facilitator pays the EIP-3009 transfer gas):
 </p>
 <ul>
diff --git a/docs/panel.html b/docs/panel.html
@@ -182,7 +182,7 @@ <h1>Seneschal Control Panel <span style="font-weight:400;color:#cfe3ff;font-size
 <!-- ── New watch ───────────────────────────────────────────────── -->
 <section class="panel active" id="panel-watch">
 	<h2>Create a new payment-monitoring watch</h2>
-	<p class="muted">You'll be asked to sign an <code>EIP-3009 transferWithAuthorization</code> for $0.10 USDC on Base. Once payment is verified by the openx402 facilitator the watch is created with $0.10 of starter credit (~5 idle days at the $0.02/day rate). Top up any time.</p>
+	<p class="muted">You'll be asked to sign an <code>EIP-3009 transferWithAuthorization</code> for $0.10 USDC on Base. Once payment is verified by Coinbase's x402 facilitator the watch is created with $0.10 of starter credit (~5 idle days at the $0.02/day rate). Top up any time.</p>
 
 	<label class="field" for="w-chain">Chain</label>
 	<select id="w-chain">
@@ -418,7 +418,7 @@ <h4>Equivalent API call</h4>
 //      topup-5,historical}) it pulls the x402 challenge from the
 //      `payment-required` response header, asks the wallet to sign
 //      an EIP-3009 transferWithAuthorization, and resubmits with the
-//      base64-encoded `x-payment` header. The openx402 facilitator
+//      base64-encoded `x-payment` header. Coinbase's CDP facilitator
 //      handles settlement; we never see a private key.
 //   4. Persists created watches in localStorage so the user can top
 //      up / poll / cancel them later — server has no concept of
diff --git a/docs/privacy.html b/docs/privacy.html
@@ -42,7 +42,7 @@
 <h1>Privacy policy</h1>
 <p class="meta">Effective 2026-05-22. Service operated under the brand name <strong>Seneschal</strong>.</p>
 
-<div class="callout info"><strong>Short version.</strong> We don&rsquo;t want your data. We store the minimum needed to deliver the service you paid for, encrypt the sensitive bits at rest, share with no one except the openx402 payment facilitator and the webhook endpoint <em>you</em> chose, and delete it all when you cancel. No cookies, no analytics, no accounts, no email, no name.</p></div>
+<div class="callout info"><strong>Short version.</strong> We don&rsquo;t want your data. We store the minimum needed to deliver the service you paid for, encrypt the sensitive bits at rest, share with no one except Coinbase&rsquo;s x402 payment facilitator and the webhook endpoint <em>you</em> chose, and delete it all when you cancel. No cookies, no analytics, no accounts, no email, no name.</p></div>
 
 <h2>1. Who we are</h2>
 <p>Seneschal is an anonymous, open-source operator of an Ethereum block builder plus a small bundle of paid data services (Private Watch, premium liquidation feeds, agent-payable single-fact endpoints). The natural person behind it operates pseudonymously as <code>Rotwang9000</code>. There is no registered company.</p>
@@ -74,15 +74,15 @@ <h2>3. Cookies and local storage</h2>
 
 <h2>4. Who we share data with</h2>
 <ul>
-	<li><strong>openx402 facilitator</strong> (<a href="https://facilitator.openx402.ai">facilitator.openx402.ai</a>). Verifies and settles your USDC payments on Base. Sees the payer address (you), the recipient address (us), the amount, and your signature. Does <em>not</em> see your view key, address, or webhook URL.</li>
+	<li><strong>Coinbase Developer Platform (CDP) x402 facilitator</strong> (<a href="https://docs.cdp.coinbase.com/x402/welcome"><code>api.cdp.coinbase.com</code></a>, operated by Coinbase). Verifies and settles your USDC payments on Base. Sees the payer address (you), the recipient address (us), the amount, and your signature, and screens the payer address against sanctions / high-risk lists (Know-Your-Transaction). Does <em>not</em> see your view key, address, or webhook URL.</li>
 	<li><strong>Your webhook endpoint.</strong> When funds land we POST a signed JSON body to the URL you gave us. You control that endpoint; we&rsquo;re a sender, not a controller.</li>
 	<li><strong>The local NFPT scanner</strong> (a Monero / Zcash full-node front-end we operate on the same machine). Receives your view key and address in memory in order to scan. Same retention as the watch row.</li>
 	<li><strong>Court orders or other lawfully binding requests.</strong> We will comply if and only if we receive a valid order in our operating jurisdiction (England &amp; Wales, see Terms §15). Because we deliberately don&rsquo;t collect identity data, there is usually nothing on you to hand over.</li>
 </ul>
 <p>We do <strong>not</strong> sell, rent, lease, or barter your data. We have no advertising partners. We have no &ldquo;data analytics&rdquo; partners. We do not enrich your data against third-party data brokers.</p>
 
 <h2>5. International transfers</h2>
-<p>Our server lives in the EU (Netherlands). The openx402 facilitator may be hosted outside the UK / EEA; transferring payment metadata to it falls under Article 49(1)(b) UK GDPR (<em>transfer necessary for performance of a contract</em>) and is limited to the payer/recipient/amount/signature tuple needed to verify the payment.</p>
+<p>Our server lives in the EU (Netherlands). Coinbase&rsquo;s CDP facilitator is operated from the United States; transferring payment metadata to it falls under Article 49(1)(b) UK GDPR (<em>transfer necessary for performance of a contract</em>) and is limited to the payer/recipient/amount/signature tuple needed to verify the payment.</p>
 
 <h2>6. Security</h2>
 <ul>
diff --git a/docs/terms.html b/docs/terms.html
@@ -40,7 +40,7 @@
 <h1>Terms of service</h1>
 <p class="meta">Effective 2026-05-22. By using any paid endpoint on <code>api.seneschal.space</code> or the control panel at <code>panel.seneschal.space</code> you agree to these terms.</p>
 
-<div class="callout danger"><strong>No refunds.</strong> All Seneschal payments settle on-chain through the openx402 facilitator. We cannot reverse a settled USDC transfer. There are no refunds for any reason, including but not limited to accidental cancellation, browser data loss, or buyer&rsquo;s remorse. Top up only what you need.</div>
+<div class="callout danger"><strong>No refunds.</strong> All Seneschal payments settle on-chain through Coinbase&rsquo;s x402 facilitator. We cannot reverse a settled USDC transfer. There are no refunds for any reason, including but not limited to accidental cancellation, browser data loss, or buyer&rsquo;s remorse. Top up only what you need.</div>
 
 <h2>1. Definitions</h2>
 <ul>
@@ -74,7 +74,7 @@ <h2>4. Eligibility &amp; acceptable use</h2>
 <h2>5. Fees, billing &amp; the credit meter</h2>
 <ul>
 	<li>All prices are denominated in USDC on Base mainnet (CAIP-2 <code>eip155:8453</code>). Live prices are exposed at <a href="https://api.seneschal.space/v1/private/info"><code>/v1/private/info</code></a> and <a href="https://api.seneschal.space/.well-known/x402"><code>/.well-known/x402</code></a>.</li>
-	<li>Payments use the <a href="https://docs.x402.org">x402 protocol</a>: you sign an EIP-3009 <code>transferWithAuthorization</code>, the openx402 facilitator settles it on-chain, we credit your Watch.</li>
+	<li>Payments use the <a href="https://docs.x402.org">x402 protocol</a>: you sign an EIP-3009 <code>transferWithAuthorization</code>, Coinbase&rsquo;s x402 facilitator settles it on-chain, we credit your Watch.</li>
 	<li>Watches drain credit at a per-day idle rate plus a per-webhook delivery rate. Both rates are published in <code>/v1/private/info</code>. The rates may change with at least 7 days&rsquo; notice on this page; we will not retro-bill credit you have already prepaid.</li>
 	<li>A one-shot <code>low_credit</code> webhook fires when your balance falls below the documented threshold so you have time to top up before the Watch pauses.</li>
 	<li>Top-ups are available in fixed tiers ($0.10 / $1 / $5) and in any variable amount from $0.10 to $25 via <code>/v1/private/topup-custom</code> (also exposed via the control panel slider).</li>
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -15,6 +15,7 @@
 		"test:watch": "node --experimental-vm-modules node_modules/.bin/jest --watch"
 	},
 	"dependencies": {
+		"@coinbase/x402": "^2.1.0",
 		"@fastify/cors": "^11.2.0",
 		"@fastify/rate-limit": "^10.3.0",
 		"@modelcontextprotocol/sdk": "^1.29.0",
diff --git a/src/config.js b/src/config.js
@@ -79,6 +79,21 @@ export const config = Object.freeze({
 	// USDC with proper EIP-712 metadata. Override at any time via
 	// X402_FACILITATOR_URL.
 	x402FacilitatorUrl: asString('X402_FACILITATOR_URL', 'https://facilitator.openx402.ai'),
+	// Coinbase Developer Platform (CDP) facilitator credentials. When
+	// BOTH are present the paywall routes settlement through Coinbase's
+	// hosted facilitator (api.cdp.coinbase.com/platform/v2/x402) instead
+	// of the permissionless openx402 URL above. Two wins from that:
+	//   1. The service is auto-catalogued in *Coinbase's* x402 Bazaar —
+	//      the largest discovery surface for agent buyers.
+	//   2. Free tier of 1,000 settlements/month, then $0.001 each.
+	// No business/KYB verification is required: a plain CDP API key is
+	// enough to *receive* x402 payments to your own wallet (verified
+	// against the live /supported endpoint). We accept the generic
+	// COINBASE_API_KEY / COINBASE_API_SECRET names too, since that's the
+	// pair the CDP portal hands you, with X402_CDP_* / CDP_* overrides
+	// for operators who keep separate keys per service.
+	x402CdpApiKeyId: asString('X402_CDP_API_KEY_ID', asString('CDP_API_KEY_ID', asString('COINBASE_API_KEY', ''))),
+	x402CdpApiKeySecret: asString('X402_CDP_API_KEY_SECRET', asString('CDP_API_KEY_SECRET', asString('COINBASE_API_SECRET', ''))),
 	// Price per call for each premium endpoint, expressed in the x402
 	// Money format ("$0.05" = 5 ¢). The facilitator quotes the USDC
 	// atomic amount on Base from this.
diff --git a/src/private-watch-custom.js b/src/private-watch-custom.js
@@ -33,6 +33,7 @@ import {
 	effectiveRatesForRow
 } from './private-watch.js';
 import { topupWatch as storeTopupWatch, getWatch as storeGetWatch } from './private-watch-store.js';
+import { createFacilitatorClient } from './x402.js';
 
 /**
  * Canonical USDC addresses per CAIP-2 network. Anything outside
@@ -162,18 +163,24 @@ export function decodePaymentHeader(headerValue) {
 }
 
 /**
- * Lazy-loaded HTTPFacilitatorClient. The @x402 toolchain depends
- * on viem + a handful of other ESM modules that take ~250 ms to
- * pull in cold; only instantiate when the first dynamic-topup
- * request actually arrives. We cache the constructor (not the
- * instance) so the test suite can swap in a fake.
+ * Lazy-loaded facilitator client. The @x402 toolchain depends on
+ * viem + a handful of other ESM modules that take ~250 ms to pull in
+ * cold; only instantiate when the first dynamic-topup request
+ * actually arrives. We cache the promise (not the instance) so the
+ * test suite can swap in a fake.
+ *
+ * Delegates to the shared `createFacilitatorClient` selector so the
+ * dynamic top-up settles through the *same* facilitator (CDP or
+ * openx402) as the static @x402/fastify routes — otherwise a payment
+ * signed against our challenge could be verified against the wrong
+ * facilitator. Receives the whole `x402Cfg` (not just a URL) because
+ * CDP mode needs the credentials, not an endpoint.
  *
  * Tests inject a fake via the `facilitatorFactory` argument to
  * `registerCustomTopupRoute`.
  */
-async function defaultFacilitatorFactory(url) {
-	const { HTTPFacilitatorClient } = await import('@x402/core/server');
-	return new HTTPFacilitatorClient({ url });
+async function defaultFacilitatorFactory(x402Cfg) {
+	return createFacilitatorClient(x402Cfg);
 }
 
 /**
@@ -223,7 +230,7 @@ export function registerCustomTopupRoute(app, deps) {
 			throw new Error('x402 paywall disabled; cannot dispatch to facilitator');
 		}
 		if (!facilitatorP) {
-			facilitatorP = Promise.resolve(facilitatorFactory(x402Cfg.facilitatorUrl));
+			facilitatorP = Promise.resolve(facilitatorFactory(x402Cfg));
 		}
 		return facilitatorP;
 	}
diff --git a/src/x402.js b/src/x402.js
diff --git a/test/x402.test.js b/test/x402.test.js
