# 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](https://seneschal.space) and Winbit32's
[mcp.winbit32.com](https://mcp.winbit32.com/mcp)
([winbit32MCP](https://github.com/FungeLLC/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](https://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`](https://github.com/Rotwang9000/x402-server-kit) —
  generic Fastify x402 paywall (facilitator selection, validated config,
  Bazaar discovery);
- [`viewkey-watch`](https://github.com/Rotwang9000/viewkey-watch) —
  Monero/Zcash view-key watch engine, credit meter and XMR/ZEC top-up
  detection;
- [`@winbit32/wallet-kit`](https://www.npmjs.com/package/@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

```bash
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:

```json
{ "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:

```js
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:

```bash
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](https://datatracker.ietf.org/doc/html/rfc1436)
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`](https://llmstxt.org) — 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:

```js
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](https://seneschal.space/gopher) — served from
[`seneschal.space/.well-known/agent.gopher`](https://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`](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`](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](https://github.com/Rotwang9000/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](https://github.com/FungeLLC/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](LICENSE).