内容
# 支付网关
一个通用的MCP + REST支付网关：为**您的**服务收费 — 并让**您的代理**接受他们的服务收费 — 而无需持有支出密钥。公开，MIT。
品牌是配置，而不是代码。相同的引擎运行 [seneschal.space](https://seneschal.space) 和 Winbit32 的 [mcp.winbit32.com](https://mcp.winbit32.com/mcp) （ [winbit32MCP](https://github.com/FungeLLC/winbit32MCP) 是此仓库的薄部署层）；指向您的名称、价格和地址的环境变量，它就是您的网关。
## 两种付款方式
**直接付款确认**
- **x402（USDC）** — 您目录中的任何REST路由都会回答 `402 Payment Required` ；代理通过Base上的 `transferWithAuthorization` 支付每笔调用费用，并重试。微价格（0.001美元的“便士神谕”层）至每路由定价，Bazaar发现。
- **带有人工干预的出站ZEC** — `make_payment` 构建一个受FROST保险库保护的隐蔽交易，返回一个`cosignUrl`深度链接 + `WB32COSIGN`二维码，付款仅在人工共同签署后存在。网关的份额 alone 不能花费。
**充值和使用**
- 计量服务（例如：查看密钥付款监视）：创建一次，然后计量下降。充值计量器使用x402（ `/v1/private/topup*` ，固定层级或自定义金额） **或支付XMR/ZEC** 到您的仅查看接收钱包 — 报价锁定汇率，唯一金额标签/备忘录标识付款人，接收方轮询器在资金到账时充值计量器。无账户，无卡，无托管余额。
- **在任意x402端点消费该计量器** （ `POST /v1/pay` ，工具 `pay_x402` ）— 付款中继。 **DORMANT / EXPERIMENTAL — 保持关闭。** 资助账户*可以*通过网关支付第三方x402服务器（网关从热浮动资金中提供USDC，结算商户的402挑战，返回响应，扣除金额+费用），具有储备→支付→结算→退款会计和可审计的`relay_payments`收据。它保持关闭（无主机注入`opts.x402Payer` ⇒ 每次调用503）因为这种托管*持有然后传输给第三方*的形状是货币传输形状。 **非托管继任者** — 用户自己的Vultisig保险库交换（Maya/NEAR-Intents）和签署x402付款，无需我们托管 — 计划在 **winbit32** 中实现。这里的代码保留并测试，但不是产品方向。
## 密钥托管
**推荐**模式是分钥：网关进程最多持有**一个FROST份额**的`t-of-n`密钥（一个`.wult`文件）。任何移动资金的工具都会返回一个共同签署二维码/深度链接；人类在共同签署者中批准（快速启动 [winbit32.com/cosign](https://winbit32.com/cosign) 应用，Winbit32桌面端的`cosign.exe`，或任何支持WB32COSIGN的签署者）。人类的份额签名是批准；网关无法单独签署。
这是推荐模式，但不是唯一模式：签署工具还接受直接提供的短语或密钥（操作员配置或显式工具输入），适用于接受持有密钥材料的运营商。文档和默认值倾向于分钥；功能永远不会因其而受到限制。
对于**接受**付款，网关仅需查看密钥：它可以看到资金到达但永远无法移动它们。
## 工具家族
| 家族 | 工具 | 需要的密钥 |
| --- | --- | --- |
| 接受 | 查看密钥监视 + HMAC Webhooks，x402付费墙，XMR/ZEC充值报价 | 仅查看密钥 |
| 解锁 *(可选)* | `paid_unlock_info/listing/browse/buy` （REST `/v1/unlock/*` ）— 支付解锁密封秘密（“付费私有文件”）：非托管ZEC/XMR（自动确认）或USDC，具有可选的公共商店饲料 | 查看密钥 + 现有主密钥（密封） |
| 制作 | `make_payment` ， `make_payment_status` ， `make_payment_info` | 一个FROST份额 + 人类共同签署（推荐），或直接提供的短语/密钥 |
| 中继 *(暂停)* | `pay_x402` ， `pay_x402_info` （REST `POST /v1/pay` ）— 托管任意消费，保持关闭（类似货币传输）；计划在winbit32中实现非托管继任者 | 主机注入的资助付款人（`opts.x402Payer`）；一个Base USDC浮动资金 |
| 钱包 | 余额，扫描作业，UTXOs，广播 | 仅查看密钥 |
| 实用工具 | 短语验证/完成/生成，Shamir分割/组合 | 无（本地，离线） |
| 信息 | 单个事实链查询（高度/费用/内存池） | 无 |
| Zcash金额 | `zec_amount_advice` ， `zec_split_plan` ， `zec_popular_amounts` （REST `GET /v1/zec/amount-advice` ， `/v1/zec/split-plan` ， `/v1/zec/popular-amounts` ）— “融合”盾牌/脱盾金额建议，大额分割规划器和实时热门金额直方图 | 无（读取）；一个zebra节点 + 索引轮询器用于实时计数 |
| Zcash总线（可选） | `zec_bus_list` ， `zec_bus_join` ， `zec_bus_status` ， `zec_bus_board` ， `zec_bus_leave` （REST `GET /v1/zec/bus` ， `GET /v1/zec/bus/:id` ， `POST /v1/zec/bus/join` ， `POST /v1/zec/bus/seat/:id/board\|leave` ）— **非托管**混合协调：许多用户离开Zcash池并具有相同的融合金额/路由窗口，以便他们的交换在链上看起来相同。网关不持有资金/密钥，不存储目的地/txids — 纯粹的汇聚点。 | `ZEC_BUS_ENABLED=1` + 可写的 `ZEC_BUS_DB` （无只读回退） |
## 构建于
从已经公开的软件包中汇集而成的单一真相来源：
- [`x402-server-kit`](https://github.com/Rotwang9000/x402-server-kit) — 通用Fastify x402付费墙（促进者选择，验证配置，Bazaar发现）；
- [`viewkey-watch`](https://github.com/Rotwang9000/viewkey-watch) — Monero/Zcash查看密钥监视引擎，信用计量器和XMR/ZEC充值检测；
- [`@winbit32/wallet-kit`](https://www.npmjs.com/package/@winbit32/wallet-kit) — 扫描器客户端 + WB32COSIGN FROST/Orchard共同签署客户端（无头启动管道）用于钱包工具和`make_payment`。
## 今日有效
| 功能 | 状态 |
| --- | --- |
| 通过x402接受USDC每次调用（HTTP 402 + `transferWithAuthorization`在Base上） | ✅ |
| 用于Monero/Zcash的查看密钥付款**网络钩子**（“当资金到账时通知我”） | ✅ |
| 具有USDC充值（固定层级 + 自定义金额）的信用计量监视 | ✅ |
| 通过向操作员的仅查看钱包支付**XMR/ZEC** | ✅ |
| 一次性历史查看密钥扫描（可花费/已花费笔记） | ✅ |
| 从短语中免费查看密钥派生（限速） | ✅ |
| 单个事实（“便士神谕”）隐私链查询（高度/费用/内存池） | ✅ |
| Zcash金额隐私顾问（免费）：“融合”盾牌/脱盾金额 + 回路自我披露警告 + 大额分割规划器，具有实时链上热门金额索引（“N其他人使用过此”） | ✅ |
| **制作**带有`cosignUrl`深度链接的出站**ZEC**付款，通过FROST共同签署 | ✅ |
| 钱包查看密钥工具（`*_zec_scan_*` ， `*_zec_utxos` ， `*_zec_broadcast` ， `*_xmr_scan_*` ） | ✅ |
| 实用工具：`phrase_validate/complete/generate` ， `shamir_split/combine` — 本地 + 离线 | ✅ |
| **付费解锁**（“付费私有文件”）：密封一个秘密，以ZEC/XMR（查看密钥，自动确认）或USDC（x402）出售；可选公共商店饲料；浏览器加密演示 — 可选 | ✅ |
| 通过**Nym**（密钥+密文浏览器到浏览器）进行平台盲支付文件交付 | 🛣️ 路线图 |
| 直接短语/密钥签署模式；出站USDC / XMR | 🛣️ 路线图 |
## 独立运行
```bash
npm ci
node bin/mcp.mjs # 代理MCP服务器（可流式HTTP）
node bin/rest.mjs # REST + x402付费墙
node bin/private-watch-poller.mjs # 监视轮询器（cron样式）
node bin/crypto-recv-poller.mjs # XMR/ZEC充值轮询器
node bin/zec-shield-index-poller.mjs # Zcash盾牌金额索引（可选）
```
代理配置：
```json
{ "mcpServers": { "myservice": { "url": "https://mcp.example.com/mcp" } } }
```
## 嵌入
将引擎安装到您自己的Fastify + MCP服务器，并注入您的配置 — 您的路由和网关的付费路由共享一个付费墙：
```js
import {
buildConfig,
registerGatewayRoutes,
registerGatewayMcpTools
} from 'payments-gateway';
const cfg = buildConfig({ ...process.env, GATEWAY_SERVICE_NAME: 'myservice' });
// REST：您的Fastify应用程序获得网关的付费路由 + 付费墙。 要为您的路由添加付费墙，请构建一个组合的x402Cfg从GATEWAY_PREMIUM_ROUTES.concat（yourRoutes）并将其传递给opts。
registerGatewayRoutes(app, { config: cfg });
// MCP：您的服务器在您的前缀下获得网关工具家族。
registerGatewayMcpTools(mcpServer, { config: cfg, toolPrefix: 'myservice' });
```
作为依赖项安装：
```bash
npm i github:Rotwang9000/payments-gateway
```
## 代理发现（Gopher over HTTPS）
为了使代理可以**廉价**地找到您的服务 — 在他们花费代币之前在HTML页面或JSON索引上 — 网关提供了一个小的，无依赖的原生HTTPS Gopher菜单服务。约定：在 **`/.well-known/agent.gopher`** 处发布一个简洁的，可钻取的服务索引，`Content-Type: application/gopher; charset=utf-8`。它是 [`llms.txt`](https://llmstxt.org) 的类型化，可导航的亲戚 — 一个发现层，**不是**MCP的替代品（这是您**调用**工具的方式）。
`gophermap`模块构建，解析和净化菜单（RFC 1436）以TLS原生“紧凑”模式，该模式减少了Gopher冗余的主机/端口字段：
```js
import {
info, menu, textItem, link, buildMenu
} from 'payments-gateway/gophermap';
// 紧凑模式是默认模式（主机+端口已删除—TLS提供它们）。
const body = buildMenu([
info('我的服务 — 机器的简洁索引。'),
menu('目录', '/.well-known/agent/catalogue'),
textItem('关于', '/.well-known/agent/about'),
link('MCP服务器', '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));
```
一行只是 `<type><label>TAB<selector>` （`1`子菜单，`0`文本叶，`h` `URL:`链接，`i`信息），以仅包含一个换行符的行结尾。 跨实际目录，紧凑菜单的测量值比等效的JSON小约29%，比最小的HTML小约32%，而渐进式披露（深入到一个分支）比拉取整个索引便宜约5倍。 实时示例 + “发布您自己的”演练： [seneschal.space/gopher](https://seneschal.space/gopher) — 来自 [`seneschal.space/.well-known/agent.gopher`](https://seneschal.space/.well-known/agent.gopher)。
## 配置
通过`src/config.js`（`buildConfig(env)`）进行环境驱动的配置。 关键组：
- **服务器**： `GATEWAY_REST_PORT` ， `GATEWAY_MCP_PORT` ， `GATEWAY_REST_HOST`
- **品牌**： `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`
- **扫描器后端**： `NFPT_BASE_URL` ， `NFPT_API_KEY`
- **私有监视**： `PRIVATE_WATCH_DB` ， `PRIVATE_WATCH_ENCRYPTION_KEY`
- **隐私RPC**： `MONERO_RPC_URL` ， `ZCASH_RPC_URL`
- **Zcash盾牌金额索引** *(始终读取；扫描器可选)*： `ZEC_SHIELD_INDEX_ENABLED` ， `ZEC_SHIELD_INDEX_DB` ， `ZEC_SHIELD_INDEX_FROM_HEIGHT` / `ZEC_SHIELD_INDEX_WINDOW_BLOCKS` ， `ZEC_SHIELD_INDEX_MAX_BLOCKS_PER_TICK` ， `ZEC_SHIELD_INDEX_MIN_BOUNDARY_ZAT`
（驱动`zec_amount_advice` / `zec_popular_amounts`工具 + `/v1/zec/*`路由；读取zebra节点，无查看密钥）
- **XMR/ZEC充值**： `XMR_RECV_ADDRESS` + `XMR_RECV_VIEW_KEY` ， `ZEC_RECV_ADDRESS` + `ZEC_RECV_UFVK` ， `CRYPTO_TOPUP_*`
- **制作付款（ZEC共同签署）**： `MAKE_PAYMENT_WULT_PATH` （+可选 `MAKE_PAYMENT_WULT_PASSWORD` ）， `MAKE_PAYMENT_WASM_DIR` （Orchard-Frost WASM工件）， `MAKE_PAYMENT_RELAY_URL` （默认为 `https://cosign.winbit32.com` ）， `MAKE_PAYMENT_PCZT_API_BASE` ， `MAKE_PAYMENT_SCANNER_BASE` ， `MAKE_PAYMENT_BIRTHDAY_HEIGHT` ，安全防护 `MAKE_PAYMENT_MAX_ZEC` / `MAKE_PAYMENT_MAX_PENDING` ，以及用于人类cosigner深度链接的 `COSIGN_APP_URL` 。
- **付费解锁**（“付费私有文件”）： `PAID_UNLOCK_ENABLED` ， `PAID_UNLOCK_DB` ， `PAID_UNLOCK_FREE_CREATE_PER_IP_PER_HOUR` ， `PAID_UNLOCK_ORDER_TTL_SEC` 。 重用 `PRIVATE_WATCH_ENCRYPTION_KEY` （密封）， `ZEC_RECV_*` / `XMR_RECV_*` 钱包 + `CRYPTO_*` oracle （原生报价）以及x402付费墙（USDC购买）。
能力在配置好密钥/地址之前保持`503 _not_configured`（或其工具根本未注册），`make_payment`工具仅在配置了`MAKE_PAYMENT_WULT_PATH`时存在，而付费解锁表面仅在`PAID_UNLOCK_ENABLED=1`时安装。
## 付费解锁（“付费私有文件”）
可选付费揭露：卖家密封一个小秘密（文件解密密钥+定位器，许可证，链接）后面跟着价格；买家**非托管**以ZEC/XMR（用查看密钥检测，资金直接流向卖家，接收方轮询器自动确认订单）或立即以x402的USDC付款，然后拉取秘密。 文件明文永远不会触摸服务器（在浏览器中加密，主机仅托管密文）；秘密在休息时与网关主密钥密封。 卖家可以将列表加入公共 **商店饲料`（`GET /v1/unlock/listings`）或仅限链接（默认）。 完整的信任模型，API表面，本地自动确认协调器和WebCrypto浏览器演示： [`docs/PAID_UNLOCK.md`](docs/PAID_UNLOCK.md)。
## 部署
- **[winbit32MCP](https://github.com/FungeLLC/winbit32MCP)** — Winbit32部署，实时运行于 `https://mcp.winbit32.com/mcp` （工具前缀 `winbit32` ）。
- **seneschal.space** — 嵌入式DeFi馈线（组合x402路由目录）。 ## 许可证
MIT — 见 [LICENSE](LICENSE) 。
