payments-gateway

A generic MCP + REST payments gateway: charge for your services — and let your agents accept payment for theirs — without ever holding a spending key. Public, MIT.

Brand is config, not code. The same engine runs seneschal.space and Winbit32's mcp.winbit32.com (winbit32MCP is a thin deployment of this repo); point the env at your own name, prices and addresses and it is your gateway.

Two ways to get paid

Direct payment with confirmation

• x402 (USDC) — any REST route in your catalogue answers 402 Payment Required; agents pay per-call with transferWithAuthorization on Base and retry. Micro-prices (a $0.001 "Penny Oracle" tier) up to per-route pricing, with Bazaar discovery.
• Outbound ZEC with a human in the loop — make_payment builds a shielded transaction from a FROST vault, returns a cosignUrl deep link
  • WB32COSIGN QR, and the payment exists only once a human co-signs it in their cosigner. The gateway's share alone cannot spend.

Top-up and use

• Credit-metered services (e.g. view-key payment watches): create once, then meter down. Top up the meter with x402 (/v1/private/topup*, fixed tiers or custom amounts) or by paying in XMR/ZEC to your view-only receiving wallet — a quote locks the rate, a unique amount-tag/memo identifies the payer, and the receive poller credits the meter when funds land. No accounts, no cards, no custodial balance.
• Spend that meter at ANY x402 endpoint (POST /v1/pay, tool pay_x402) — the payer relay. DORMANT / EXPERIMENTAL — kept off. A funded account could pay a third-party x402 server through the gateway (gateway fronts USDC from a hot float, settles the merchant's 402 challenge capped, returns the response, debits amount + fee), with reserve→pay→settle→refund accounting and auditable relay_payments receipts. It stays off (no host-injected opts.x402Payer ⇒ every call 503s) because this custodial hold-then-transmit-to-third-parties shape is money-transmission-shaped. The non-custodial successor — the user's OWN Vultisig vault swaps (Maya/NEAR-Intents) and signs the x402 payment, no custody by us — is planned in winbit32. The code here is retained and tested but is not the product direction.

Key custody

The recommended mode is split-key: the gateway process holds at most one FROST share of a t-of-n key (a .wult file). Any tool that moves funds returns a cosign QR / deep link; a human approves in a cosigner (the fast-boot winbit32.com/cosign app, cosign.exe in the Winbit32 desktop, or any WB32COSIGN-speaking signer). The human's share signature IS the approval; nothing the gateway can sign alone.

That is the recommended mode, not the only one: signing tools also accept directly supplied phrases or keys (operator config or explicit tool input) for operators who accept holding key material. Docs and defaults steer towards split-key; functionality is never gated on it.

For accepting payments the gateway is view-key-only: it can see funds arrive but can never move them.

Tool families

Family	Tools	Keys needed
accept	view-key watches + HMAC webhooks, x402 paywall, XMR/ZEC top-up quotes	view keys only
unlock (opt-in)	paid_unlock_info/listing/browse/buy (REST /v1/unlock/*) — pay-to-reveal a sealed secret ("paid private file"): non-custodial ZEC/XMR (auto-confirmed) or USDC, with an opt-in public shop feed	view keys + the existing master key (sealing)
make	make_payment, make_payment_status, make_payment_info	one FROST share + human cosign (recommended), or a directly supplied phrase/key
relay (dormant)	pay_x402, pay_x402_info (REST POST /v1/pay) — custodial spend-anywhere, kept OFF (money-transmission-shaped); non-custodial successor planned in winbit32	host-injected funded payer (opts.x402Payer); a Base USDC float
wallet	balances, scan jobs, UTXOs, broadcast	view keys only
utility	phrase validate/complete/generate, Shamir split/combine	none (local, offline)
info	single-fact chain queries (height/fee/mempool)	none

Built on

One source of truth, assembled from already-public packages:

• x402-server-kit — generic Fastify x402 paywall (facilitator selection, validated config, Bazaar discovery);
• viewkey-watch — Monero/Zcash view-key watch engine, credit meter and XMR/ZEC top-up detection;
• @winbit32/wallet-kit — scanner clients + the WB32COSIGN FROST/Orchard cosign client (headless initiator pipeline) used by the wallet tools and make_payment.

What works today

Capability	Status
Accept USDC per-call via x402 (HTTP 402 + transferWithAuthorization on Base)	✅
View-key payment webhooks for Monero/Zcash ("ping me when funds land")	✅
Credit-metered watches with USDC top-ups (fixed tiers + custom amounts)	✅
Fund a watch by paying in XMR/ZEC to the operator's view-only wallet	✅
One-off historical view-key scans (spendable/spent notes)	✅
Free view-key derivation from a phrase (rate-limited)	✅
Single-fact ("Penny Oracle") privacy-chain queries (height/fee/mempool)	✅
Make outbound ZEC payments via FROST co-signing, with cosignUrl deep links	✅
Wallet view-key tools (*_zec_scan_*, *_zec_utxos, *_zec_broadcast, *_xmr_scan_*)	✅
Utility tools: phrase_validate/complete/generate, shamir_split/combine — local + offline	✅
Paid unlock ("paid private file"): seal a secret, sell it for ZEC/XMR (view-key, auto-confirmed) or USDC (x402); opt-in public shop feed; browser-encrypt demo — opt-in	✅
Platform-blind paid-file delivery over Nym (key + ciphertext browser-to-browser)	🛣️ roadmap
Direct phrase/key signing mode; outbound USDC / XMR	🛣️ roadmap

Running it standalone

npm ci
node bin/mcp.mjs     # MCP server for agents (Streamable HTTP)
node bin/rest.mjs    # REST + x402 paywall
node bin/private-watch-poller.mjs    # watch poller (cron-style)
node bin/crypto-recv-poller.mjs      # XMR/ZEC top-up poller

Agent config:

{ "mcpServers": { "myservice": { "url": "https://mcp.example.com/mcp" } } }

Embedding it

Mount the engine onto your own Fastify + MCP servers and inject your config — your routes and the gateway's paid routes share one paywall:

import {
	buildConfig,
	registerGatewayRoutes,
	registerGatewayMcpTools
} from 'payments-gateway';

const cfg = buildConfig({ ...process.env, GATEWAY_SERVICE_NAME: 'myservice' });

// REST: your Fastify app gains the gateway's paid routes + paywall. To
// paywall your own routes too, build a combined x402Cfg from
// GATEWAY_PREMIUM_ROUTES.concat(yourRoutes) and pass it in opts.
registerGatewayRoutes(app, { config: cfg });

// MCP: your server gains the gateway tool families under your prefix.
registerGatewayMcpTools(mcpServer, { config: cfg, toolPrefix: 'myservice' });

Install as a dependency:

npm i github:Rotwang9000/payments-gateway

Agent discovery (Gopher over HTTPS)

So agents can find your services cheaply — before they spend tokens on an HTML page or a JSON index — the gateway ships a tiny, dependency-free primitive for serving a Gopher menu natively over HTTPS. The convention: publish a terse, drill-down service index at /.well-known/agent.gopher with Content-Type: application/gopher; charset=utf-8. It is a typed, navigable cousin of llms.txt — a discovery layer, not a replacement for MCP (which is how you call a tool).

The gophermap module builds, parses and sanitises menus (RFC 1436) in a TLS-native "compact" mode that drops Gopher's redundant host/port fields:

import {
	info, menu, textItem, link, buildMenu
} from 'payments-gateway/gophermap';

// Compact mode is the default (host + port dropped — TLS supplies them).
const body = buildMenu([
	info('My services — terse index for machines.'),
	menu('Catalogue', '/.well-known/agent/catalogue'),
	textItem('about', '/.well-known/agent/about'),
	link('MCP server', 'https://mcp.example.com/')
]);

app.get('/.well-known/agent.gopher', (req, reply) =>
	reply
		.header('content-type', 'application/gopher; charset=utf-8')
		.header('cache-control', 'public, max-age=600')
		.send(body));

A line is just <type><label>TAB<selector> (1 submenu, 0 text leaf, h URL: link, i info), terminated by a line containing only .. Across a real directory the compact menu measures ~29% smaller than the equivalent JSON and ~32% smaller than minimal HTML, and progressive disclosure (drilling into one branch) is ~5× cheaper than pulling a whole index. Live example + a "publish your own" walkthrough: seneschal.space/gopher — served from seneschal.space/.well-known/agent.gopher.

Configuration

Environment-driven via src/config.js (buildConfig(env)). Key groups:

• Server: GATEWAY_REST_PORT, GATEWAY_MCP_PORT, GATEWAY_REST_HOST
• Brand: GATEWAY_SERVICE_NAME, GATEWAY_TOOL_PREFIX, GATEWAY_WEBHOOK_SIGNATURE_HEADER
• x402: X402_RECIPIENT_ADDRESS, X402_NETWORK, X402_FACILITATOR_URL, X402_CDP_API_KEY_ID / X402_CDP_API_KEY_SECRET, X402_*_PRICE
• Scanner backend: NFPT_BASE_URL, NFPT_API_KEY
• Private watch: PRIVATE_WATCH_DB, PRIVATE_WATCH_ENCRYPTION_KEY
• Privacy RPC: MONERO_RPC_URL, ZCASH_RPC_URL
• XMR/ZEC top-ups: XMR_RECV_ADDRESS + XMR_RECV_VIEW_KEY, ZEC_RECV_ADDRESS + ZEC_RECV_UFVK, CRYPTO_TOPUP_*
• Make payments (ZEC co-sign): MAKE_PAYMENT_WULT_PATH (+ optional MAKE_PAYMENT_WULT_PASSWORD), MAKE_PAYMENT_WASM_DIR (orchard-frost WASM artefacts), MAKE_PAYMENT_RELAY_URL (default https://cosign.winbit32.com), MAKE_PAYMENT_PCZT_API_BASE, MAKE_PAYMENT_SCANNER_BASE, MAKE_PAYMENT_BIRTHDAY_HEIGHT, the safety rails MAKE_PAYMENT_MAX_ZEC / MAKE_PAYMENT_MAX_PENDING, and COSIGN_APP_URL for the human-facing cosigner deep links.
• Paid unlock ("paid private file"): PAID_UNLOCK_ENABLED, PAID_UNLOCK_DB, PAID_UNLOCK_FREE_CREATE_PER_IP_PER_HOUR, PAID_UNLOCK_ORDER_TTL_SEC. Reuses PRIVATE_WATCH_ENCRYPTION_KEY (sealing), the ZEC_RECV_* / XMR_RECV_* wallet + CRYPTO_* oracle (native quotes) and the x402 paywall (USDC buys).

A capability stays 503 *_not_configured (or its tools are simply not registered) until its keys/addresses are set — the make_payment tools only exist when MAKE_PAYMENT_WULT_PATH is configured, and the paid-unlock surface only mounts when PAID_UNLOCK_ENABLED=1.

Paid unlock ("paid private file")

Opt-in pay-to-reveal: a seller seals a small secret (a file decryption key + locator, a licence, a link) behind a price; a buyer pays non-custodially in ZEC/XMR (detected with a view key — funds go straight to the seller, and the receive-poller auto-confirms the order) or instantly in USDC over x402, then pulls the secret. The file plaintext never touches the server (encrypt in-browser, host only the ciphertext); the secret is sealed at rest with the gateway master key. Sellers can opt a listing into a public shop feed (GET /v1/unlock/listings) or keep it link-only (default). Full trust model, API surface, the native auto-confirm reconciler and the WebCrypto browser demo: docs/PAID_UNLOCK.md.

Donation overlay (streamer alerts from a UFVK)

LiveZEC-style on-stream Zcash donation alerts with no accounts and no custody, built on the same UFVK scanner as Private Watch:

1. POST /v1/overlay { ufvk, address, label?, minZec?, birthdayHeight?, amountUsdCents? } → returns an unguessable overlayId (the OBS capability URL), a one-shot ownerToken (top-up/cancel) and a ZEC funding quote (memo token to our receiving wallet — the same rail as topup-crypto, so streamers pay us in ZEC with no USDC/EVM step anywhere). The overlay starts immediately on a small grace credit.
2. Add public/donation-overlay.html?overlay=ov_… as an OBS browser source (transparent background; &show=confirmed and &hold=12 tune behaviour). It polls GET /v1/overlay/:id/events?sinceId=N — plain JSON, CORS-open, cursor paginated — so any custom overlay/bot can consume the same feed.
3. The receive-poller tick scans each funded overlay's wallet through NFPT (bounded from the last scanned height) and turns new incoming shielded notes into events: amount + decrypted memo, seen (~1 block) then confirmed (3 blocks). The first scan is a suppressed baseline so wallet history never floods the stream.

Billing is the standard prepaid meter ($0.02/day; POST /v1/overlay/:id/topup mints fresh ZEC quotes). Data kept: the UFVK (AES-256-GCM under the gateway master key), the public receive address, an optional label. Events are pruned after 30 days; there are no accounts, emails or IP logs. Streamers should use a donation-only wallet — a UFVK reveals ALL incoming amounts + memos for that wallet to whoever holds it (that's us, encrypted, and anyone the streamer leaks it to).

Ziving (fundraising pages — ziving.org)

Ziving extends the donation overlay into JustGiving-style campaign pages on shielded ZEC:

1. POST /v1/ziving/page { slug, label, story?, goalZec?, ufvk, address, amountUsdCents? } → public page at ziving.org/p.html?slug=…, same owner token + ZEC funding quote as the overlay.
2. GET /v1/ziving/page/:slug — page metadata, goal progress, donate address.
3. GET /v1/ziving/page/:slug/events — live gift feed (page + OBS overlay).

Winbit32 deep links for wallet creation are returned from GET /v1/ziving. Set ZIVING_PAGE_URL_BASE and OVERLAY_PAGE_URL_BASE to your hosted static site.

Deployments

• winbit32MCP — the Winbit32 deployment, live at https://mcp.winbit32.com/mcp (tool prefix winbit32).
• seneschal.space — embedded alongside its own DeFi feeds (combined x402 route catalogue).

Licence

MIT — see LICENSE.