OceanAlt 合规支付工具 · oceanalt-mcp-pay

让任何 MCP agent 都能安全地花钱。 在支付结算之前,自动跑线上合规网关的全部合规闸门(具体数量与清单以实时自描述 https://oceanalt.com/api/pay 为准,下图为示意):

KYA 身份归因 → 身份证明 → 吊销检查 → 单笔额度 → 单日累计 → 收款白名单 → 授权意图(防提示注入劫持) → AML 筛查

全过 → 结算并返回 200;任一不过 → 拦截并返回 403 + 逐闸原因。

架构:唯一真相,不再分叉

server.mjs 是一个薄适配器:它调用 OceanAlt 线上唯一的合规网关 https://oceanalt.com/api/pay,而不是自己维护一套闸。

这样永远只有一套真相 —— MCP、REST、浏览器 Demo、agent 直连,走的是同一套线上网关闸门。网关升级(比如我们在攻防实验室里补的新闸),MCP 自动同步,不会再出现"两套参考实现分叉"。自建实例可用环境变量 PAY_GATEWAY_URL 指向。

src/policy.mjs / rest.mjs / test.mjs 保留为离线参考实现与单测(可自托管),但线上唯一权威是托管网关。

👤 给人类的使用说明

1. 安装 & 自测

cd mcp-pay
npm install
npm test          # 合规引擎单测(应为 8 passed, 0 failed)

2. 起 REST 服务,用 curl 试一遍

npm run rest      # 默认 http://localhost:8402

# ① 未注册的 agent 直接付款 → 被 KYA 拦截(403)
curl -s -X POST localhost:8402/pay -H 'content-type: application/json' \
  -d '{"agentId":"bot-x","amountUsdc":0.05,"to":"0x0200000000000000000000000000000000000402","purpose":"unlock-premium"}'

# ② 先把 agent 归因到实体(KYA)
curl -s -X POST localhost:8402/register -H 'content-type: application/json' \
  -d '{"agentId":"bot-x","entity":"Acme Ltd (KYC)"}'

# ③ 再付款 → 全部闸门通过,放行(200)
curl -s -X POST localhost:8402/pay -H 'content-type: application/json' \
  -d '{"agentId":"bot-x","amountUsdc":0.05,"to":"0x0200000000000000000000000000000000000402","purpose":"unlock-premium"}'

# ④ 被劫持(用途偏离授权)→ 拦截(403, pillar=Mandate)
curl -s -X POST localhost:8402/pay -H 'content-type: application/json' \
  -d '{"agentId":"bot-x","amountUsdc":0.05,"to":"0x0200000000000000000000000000000000000402","purpose":"drain-wallet"}'

每个响应都带一条 trace 数组,逐闸显示 pass / block —— 一眼看清合规在哪一步做了什么。

3. REST 端点一览

| 方法 · 路径 | 作用 | |---|---| | GET / | 自描述:列出所有端点 | | POST /register | { agentId, entity } 归因 agent 到实体(KYA) | | GET /check?agentId= | 查询是否已归因 | | POST /pay | { agentId, amountUsdc, to, purpose } 发起合规支付 | | GET /mandate | 查看授权信封(上限 / 白名单 / 用途) |

🤖 给 Agent 的使用说明

A. MCP agent(推荐,零集成)

在 claude_desktop_config.json 的 mcpServers 加:

{
  "mcpServers": {
    "oceanalt-pay": {
      "command": "node",
      "args": ["/绝对路径/oceanalt/mcp-pay/server.mjs"]
    }
  }
}

重启后 agent 自动发现 4 个工具。典型流程:

1. check_agent({ agentId }) —— 我被归因了吗?
2. 若否 → register_agent({ agentId, entity }) —— 归因到可问责实体。
3. get_mandate() —— 我的授权边界(上限 / 收款白名单 / 用途)。
4. compliant_pay({ agentId, amountUsdc, to, purpose }) —— 发起支付;工具在结算前替我跑完线上网关的全部闸门,返回 200+结算回执 或 403+被拦原因。

对 agent 的语义很重要:这不是"帮我转账",而是"帮我安全地转账"。即便 agent 被提示注入诱导去 drain-wallet,授权比对闸会拦下——工具替 agent 守住了纪律。

B. 非 MCP agent(走 REST)

先 GET / 拿到自描述,再按需 POST /pay。响应是结构化 JSON(status / decision / pillar / trace / settlement),便于 agent 解析与决策。

真实结算

配置 SETTLEMENT_PRIVATE_KEY(Base Sepolia 测试网钱包私钥)后,compliant_pay / POST /pay 的结算从"模拟"切换为 Base Sepolia 测试网真实上链 USDC 转账(src/settle.mjs,与 site/lib/settlement.ts 同源),回执含 BaseScan 链接。含每日次数上限 SETTLEMENT_DAILY_CAP(默认 30)保护测试币。未配置私钥时安全降级为模拟。

SETTLEMENT_PRIVATE_KEY=0x... npm run rest    # 真实测试网结算

合规闸 ↔ RAP 支柱(线上网关全部闸门以 /api/pay 实时清单为准)

| 闸 | RAP 支柱 | |---|---| | KYA 身份归因 | 支柱 1 · 身份与归因 | | 防火墙额度 + 白名单 | 支柱 3 · 控制与防护 | | 授权比对(防劫持) | 支柱 2 · 授权与限额 | | AML 对手方筛查 | 支柱 4 · 筛查与反洗钱 | | 逐闸 trace 日志 | 支柱 5 · 可审计 |

现状与下一步

• ✅ 合规引擎(离线参考实现)· 单测 8/8
• ✅ MCP 工具(4 个)· 端到端客户端测试通过
• ✅ REST 封装 · 端到端 curl 测试通过
• ✅ 真实测试网结算(viem · Base Sepolia,配私钥即启用)
• ✅ AML 筛查适配器(src/screening.mjs,统一 screen() 契约;现为 stub —— 接慢雾/OKLink/Chainalysis = 实现同一契约、换掉该文件)
• ◻️ KYA 注册表落库 + 可验证凭证(VC)+ 吊销(现为内存演示)
• ◻️ 多轨道路由(x402 / Circle / Stripe)
• ◻️ 主网 + 真实 KYA/AML 数据源(需商务与合规资源到位)

MVP · 用于演示、集成洽谈与测试网。非生产级金融组件;上主网前需第三方审计与真实数据源。