ap2-iso20022

ap2-iso20022：Agent 支付授权 → 符合汇款规范的 ISO 20022

将 AP2（Google 的 Agent Payments Protocol）和 x402 （Coinbase 的 HTTP-402）授权转换为 ISO 20022 pain.001 / pacs.008 记录 — 并提供消费限额、过期时间和授权防护措施，以及一个 MCP 服务。 这些 Agent 支付协议用于授权付款；这个库会将授权转换为实际完成结算所需的银行轨道报文——这是银行卡网络和稳定币未覆盖的轨道。

最新版本：v0.0.7：提供 11 个 MCP 工具，支持 stdio、可流式 HTTP 或 SSE；纯 Python（仅依赖 mcp）；分支覆盖率 100%；支持 Python 3.10+。输出可直接传入 pain001 / pacs008，以生成符合汇款规范的 XML。 属于 ISO 20022 MCP 套件。

---

为什么需要它

拥有已签名 AP2 授权（或 x402 付款授权）的 Agent 可以证明 自己获准付款——但这些协议都不会生成银行转账所需的 pain.001。 ap2-iso20022 补上了这一环。由于资金转移影响重大，它只负责转换和验证——生成 ISO 记录与生成并发送记录刻意分开，因此实际付款仍是一个明确且受保护的步骤。

安装

pip install ap2-iso20022
# or run the MCP server without installing:
uvx --from ap2-iso20022 ap2-iso20022-mcp

MCP 客户端配置（例如 Claude Desktop）：

{
  "mcpServers": {
    "ap2-iso20022": {
      "command": "ap2-iso20022-mcp"
    }
  }
}

传输方式

一条命令行，三种传输方式：

命令	传输方式	端点	协议修订版本
ap2-iso20022-mcp	stdio	客户端启动该进程	2026-07-28、2025-11-25
ap2-iso20022-mcp --transport streamable-http	可流式 HTTP	http://127.0.0.1:8000/mcp	同一端点支持 2026-07-28（无状态，server/discover）和 2025-11-25（initialize、Mcp-Session-Id）；响应以服务器发送事件的形式流式传输，GET 用于打开服务器到客户端的数据流
ap2-iso20022-mcp --transport sse	HTTP+SSE（2024-11-05）	http://127.0.0.1:8000/sse 和 /messages/	适用于仍期待旧版传输方式的客户端

--host 和 --port 可更改绑定地址（默认值为 127.0.0.1 和 8000）。HTTP 传输方式本身不提供身份验证：请绑定到 loopback 地址，或在绑定到可路由地址之前，将服务置于可信网关之后。每个版本都会通过 scout 验证可流式 HTTP 的两种协议版本，并使用 MCP SDK 客户端验证 SSE；请参阅 ADR 0001。

{
  "mcpServers": {
    "ap2-iso20022": { "url": "http://127.0.0.1:8000/mcp" }
  }
}

流程：规范化 → 防护检查 → 转换

from ap2_iso20022 import bridge

# 1. Normalise the protocol payload into a canonical mandate.
mandate = bridge.from_ap2({
    "intent_id": "AP2-CoffeeRun-7",
    "payer": "Alice's Shopping Agent",
    "payer_account": "DE89370400440532013000",
    "merchant_name": "Blue Bottle Coffee",
    "payee_account": "GB29NWBK60161331926819",
    "amount": "12.50", "currency": "EUR", "memo": "oat latte",
    "spending_limit": "50.00",
    "signature": "eyJ...", "signature_type": "jws",
})

# 2. Guardrail before it becomes a payment.
check = bridge.check_mandate(mandate, as_of="2026-03-02T09:00:00")
assert check["ok"]          # required fields ok, within cap, not expired, signed

# 3. Convert to a pain.001 record that feeds pain001 -> wire-valid XML.
record = bridge.to_pain001(mandate)   # exact pain001 field names + JSON number amounts

工具

• normalize_ap2 — AP2 授权载荷 → 规范化授权。
• normalize_x402 — x402 付款载荷 → 规范化授权。
• check_mandate — 防护检查：必填字段、消费限额、过期时间（使用 as_of）、授权证明。
• to_pain001 — 规范化授权 → pain.001 记录（客户贷记转账）。
• to_pacs008 — 规范化授权 → pacs.008 记录（金融机构间转账）。

输出字段名称和类型与 pain001 / pacs008 的要求一致 （已根据其 JSON 架构验证），因此 to_pain001(mandate) → pain001 generate_message → 无需胶水代码即可生成符合 XSD 的 pain.001。

防护措施

check_mandate 返回 {ok, violations, warnings}：

• 必填字段 — 付款人／收款人的姓名和账户、金额、币种
• 消费限额 — 存在限额时，要求 amount <= max_amount
• 过期时间 — 传入 as_of 时，拒绝已过期的授权
• 授权证明 — 不存在 proof_type／proof_value 时发出警告

它不会转移资金；它会告知你该授权是否可以安全执行。

套件

这是一个由供应商中立、原生支持 Python 的 ISO 20022 MCP 服务组成的系列：

• iso20022-mcp — 跨系列的统一网关。
• pain001-mcp · pacs008-mcp — 生成此桥接器所需的 XML。
• reconcile-mcp — 对账单与支付进行对账。
• camt-exceptions — E&I 消息（取消、调查）。

开发

git clone https://github.com/sebastienrousseau/ap2-iso20022
cd ap2-iso20022
python -m venv .venv && . .venv/bin/activate
pip install -e . && pip install pytest pytest-cov ruff black mypy
pytest                      # 100% branch coverage gate
ruff check ap2_iso20022 tests && black --check ap2_iso20022 tests && mypy ap2_iso20022

许可证

根据 Apache License 2.0 版（LICENSE）授权。

---

mcp-name: io.github.sebastienrousseau/ap2-iso20022