Boundra — Payment Approval Gateway for AI Agents

Boundra · 面向 AI Agent 的付款审批网关

Boundra（boundra.io）— 为 Agent 付款划定边界。 Agent 付款的边界层：每笔款项转出前，先回答 “这笔付款到底该不该发生？”

我们的主张：Agent 付款的机会不在于“如何付款”（协议已解决这个问题），而在于“是否付款”。

一条自然语言规则 → 编译为策略 → 真正评估 Agent 尝试的每笔付款 → 放行 / 询问人工 / 否决，并留下完整的审计记录。

两种运行模式：

• 离线模拟（demo.py）：仅使用标准库、自包含的模拟商户和钱包、零依赖、无需联网
• 真实协议（demo/demo_real.py）：标准 MCP 服务 + 真实 x402 SDK + Base Sepolia 测试网

数据流

策略和密钥由用户保管；网关只读；只有哈希承诺会上链。撤销始终免费，没有例外。

要将 Boundra 集成到你的 Agent 中？ 请参阅 docs/INTEGRATION.md — 托管 API、x402 SDK 钩子 和 MCP 接入方式，均附有经过测试的代码。

60 秒内运行演示

# 1. Hit the hosted evaluation API — a real, public x402 merchant
curl -X POST https://api.boundra.io/evaluate/basic \
  -H 'Content-Type: application/json' \
  -d '{"intent":{"amount":0.01,"recipient":"api.weather.com","purpose":"weather data"}}'
# → {"decision":"ALLOW",...}  ·  semantic layer: 100 free calls per agent,
#   then $0.003 via x402 — settled for real on Base mainnet (USDC)

# 2. Local end-to-end simulation — a data-procurement agent's day
.venv/bin/python demo/simulate_agent.py
# signed policy publish → ALLOW / DENY (limit) / ASK → user-signed approval token
# → prompt-injection blocked → audit trail, plus a dogfood call to api.boundra.io

# 3. One-line MCP install + 2-minute policy wizard
uvx --from git+https://github.com/gobeyondfj-cmd/boundra boundra-mcp     # stdio server
uvx --from git+https://github.com/gobeyondfj-cmd/boundra boundra-init    # wallet → template → sign → anchor
uvx --from git+https://github.com/gobeyondfj-cmd/boundra boundra-approve # sign an ASK challenge

完整流程，一步步来

约 10 分钟即可从零开始，创建并签署一项强制执行的策略。无需账户或控制面板 — 你的钱包密钥就是你的身份。

0 · 试用托管 API （30 秒，无需安装）

curl -X POST https://api.boundra.io/evaluate/basic \
  -H 'Content-Type: application/json' \
  -d '{"intent":{"amount":0.01,"recipient":"api.weather.com","purpose":"weather data"}}'

1 · 绑定身份 — 钱包就是账户

uvx --from git+https://github.com/gobeyondfj-cmd/boundra boundra-init

创建或导入 Base 钱包。无需注册，也无需邮箱 — 私钥绝不会离开你的设备，而你的地址就是你在整个系统中的身份。

2 · 设置策略

向导提供模板（个人助手 / 旅行 / 开发 API / 采购），也允许你用简单英语编写自己的规则，然后编译规则并准确展示将强制执行的内容 — 在签署任何内容之前。

3 · 签署并发布

你使用钱包密钥（EIP-191）签署策略文档。文档会以带版本的形式发布，并将哈希承诺锚定到链上。从此刻起，网关对所有 Agent 都是只读的 — 没有你的密钥，就无法更改策略。

4 · 将 MCP 服务挂载到你的 Agent 中

托管式（无需安装、支持多租户；发布已签署的策略前默认拒绝）：

{ "mcpServers": { "boundra": { "url": "https://api.boundra.io/mcp" } } }

或自行托管：

{ "mcpServers": { "boundra": { "command": "uvx",
  "args": ["--from", "git+https://github.com/gobeyondfj-cmd/boundra", "boundra-mcp"] } } }

5 · 每笔付款都必须在签署前获得裁决

你的 Agent 调用 evaluate_payment；5 阶段流水线会给出结果： ALLOW（签署并结算）/ DENY（签署前中止，链上不留任何痕迹）/ ASK（绑定到这笔确切付款的挑战）。

6 · Agent 发起询问时，由你来决定

uvx --from git+https://github.com/gobeyondfj-cmd/boundra boundra-approve

粘贴 ASK 挑战，在你的设备上签署 — Agent 随后会携带已签署的批准令牌重试。伪造、重新绑定或重放的令牌都会被拒绝。

7 · 查看、更新、撤销

get_spend_report / get_audit_trail / get_policy_versions 让你在日常使用中始终掌控全局。每次策略变更都会生成一个新的已签署版本（set_policy）；revoke_policy 会立即启用默认拒绝，而且永久免费。

快速开始（从源码安装）

cd boundra

# Mode 1: offline simulation (run this first — the full flow in 30 seconds)
python demo/demo.py

# Mode 2: real x402 + MCP
python -m venv .venv && .venv/bin/pip install \
    "x402[evm,httpx]" mcp eth-account fastapi uvicorn
.venv/bin/python tests/test_mcp_client.py    # MCP protocol-level tests
.venv/bin/python demo/setup_wallets.py       # generate Base Sepolia test wallets + faucet guide
.venv/bin/python demo/demo_real.py           # real protocol end-to-end (settles on-chain after funding)

架构：网关所处的位置

Agent framework (Claude / custom)
   │  MCP protocol (stdio)
   ▼
mcp_server.py  ──→  policy.py 5-stage evaluation pipeline
(policy decision     semantic → whitelist → limit → approval → budget
 point)
   ▲
   │ on_before_payment_creation hook (x402 SDK v2 native interception point)
x402_buyer.py ──sign (EIP-3009)──→ x402 server ──→ facilitator ──→ Base Sepolia

关键发现：x402 SDK v2 原生提供 on_before_payment_creation 钩子，以及 register_policy / set_spend_controls — 策略层并非后加的功能，而是官方协议栈预留的扩展点。这验证了切入点的价值。

文件一览

boundra/
├── policy.py                 intent compilation (NL→Policy, bilingual CN/EN) + 5-stage pipeline + platform red lines
├── signed_policy.py          ★ signed policy documents + version chain + revocation (keccak)
├── approval.py               ★ signed approval tokens (challenge → user signs → gateway verifies)
├── mandate.py                ★ task Mandates: single-use authorization, burned after use (pipeline layer 4)
├── templates.py              ★ policy template library (personal assistant / travel / dev API / procurement)
├── chain_anchor.py           ★ anchor backends: local simulation + real Base Sepolia (web3)
├── gateway.py                gateway core v3: 4-layer stacking + token verification + Mandate + revocation
├── rail_adapters.py          ★ rail adapter layer: evaluation core decoupled from settlement rails (x402 first)
├── mcp_server.py             ★ standard MCP server (11 tools, stdio)
├── boundra_cli.py            ★ boundra-init (policy wizard) + boundra-approve (challenge signer)
├── contracts/
│   └── PolicyAnchor.sol      ★ on-chain commitment contract (owner-write, anyone-read)
├── demo/
│   ├── simulate_agent.py     ★ end-to-end user journey simulation (MCP + hosted API dogfood)
│   ├── demo_policy.py        signed-policy demo (impersonation / unsigned / tampering attacks all blocked)
│   ├── demo_real.py          real-protocol end-to-end orchestration
│   ├── x402_resource_server.py  real x402 paywall server (FastAPI middleware)
│   ├── x402_buyer.py         real x402 buyer, evaluated by the MCP gateway before signing
│   ├── setup_wallets.py      Base Sepolia test wallet generation
│   └── demo.py / merchant.py / agent.py   offline simulation (zero dependencies)
├── tests/
│   ├── test_product.py       ★ product tests (22 assertions)
│   └── test_mcp_client.py    MCP protocol-level tests
├── docs/
│   ├── dataflow.png          data-flow diagram (English)
│   └── render_*.py           diagram renderers (architecture / flow / use-case / data flow)
└── state/audit.jsonl         audit trail (generated at runtime, gitignored)

签名策略：信任根是用户的密钥，而不是网关的数据库（v2）

策略是由用户的钱包签名的文档，而不是网关配置中的一条记录：

user private key signature ──→ PolicyDocument (NL rule + compiled artifact + prev_hash + version)
                      │  three checks: signer == owner, versions sequential, prev_hash unbroken
                      ▼
              PolicyStore (version chain) ──→ LocalAnchor (simulated commitment; production writes to contract)
                      │
                      ▼  check_integrity before every evaluation (signature + anchor)
              5-stage pipeline; audit records cite policy version + hash

• Agent 只能读取：没有用户的私钥，set_policy 总会失败——冒充、未签名和篡改后的提交都会被拦截（demo/demo_policy.py 中有 7 种情形）
• 两个叠加的作用域：用户级（适用于所有 Agent 的规则）× Agent 级（针对各个 Agent 的规则）；以最严格的判定为准
• 每次版本升级都需要签名：v2 必须引用 v1 的哈希；篡改任何历史版本都会导致签名无效、链条断裂
• 隐私设计：只有哈希承诺会上链；除非用户选择披露，否则策略明文永远不会离开设备

运行：.venv/bin/python demo/demo_policy.py

判定凭证：每项决策都附有签名回执（v4）

每个 evaluate_payment 响应都包含一个 credential——由平台密钥（EIP-191）签名的 boundra.verdict/v1 回执。它回答了这样一个问题：“谁能证明这次 ALLOW / DENY / ASK 确实发生过，并且是在此策略下，针对这一确切支付意图作出的？”

• 绑定意图：intent_hash = 对规范化的 {amount, recipient, purpose} 计算 sha256；凭证无法重新附加到另一笔支付上
• 绑定策略：policy_refs 列出所用策略版本的哈希，可与链上锚点进行比对
• 绑定审计日志：audit_id 链接到服务端审计记录
• 任何人都可离线验证：去除 proof，将负载规范化（键排序、紧凑分隔符），恢复 EIP-191 签名者——其地址必须与 issuer 以及平台地址相同： 0xF30955B6Be768370Da13fca237A5f252F6081d1C（这也是接收 x402 收入的地址——签名和结算使用同一身份）。密钥发布于 GET https://api.boundra.io/verdict-key。

from verdict_credential import verify_credential
ok, why = verify_credential(verdict["credential"])   # offline, no API call

除非设置了 BOUNDRA_VERDICT_KEY，可自托管网关不会附加凭证——未签名模式仍完全向后兼容。

MCP 服务工具

工具	用途	调用方
evaluate_payment	支付前评估。ALLOW 则继续 / DENY 则中止 / ASK 则返回由用户签名的质询；使用 approval_token 重试	Agent
set_policy	特权操作：提交新的策略版本；需要所有者的 EIP-191 签名	仅限用户
revoke_policy	特权操作：撤销策略链（立即默认拒绝，永久免费）	仅限用户
get_policy_versions	策略版本历史（链和哈希，可与链上承诺进行比对）	任何人
get_policy	查看旧版回退策略	任何人
get_spend_report	今日支出 / 剩余预算	Agent
get_audit_trail	审批审计记录	Agent
request_policy_change	Agent 请求用户更改策略（进入队列，绝不自行应用）	Agent
list_templates / render_template	策略模板辅助工具	Agent

挂载到 Claude Desktop

只需一行——uvx 会解析依赖项并启动服务：

{
  "mcpServers": {
    "boundra": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/gobeyondfj-cmd/boundra", "boundra-mcp"]
    }
  }
}

首次运行时，使用 boundra-init 向导（同一软件包）：创建 / 导入钱包 → 选择策略模板 → 签名 → 通过 MCP 发布，约需 2 分钟。 当 Agent 遇到 ASK 时，运行 boundra-approve 并粘贴质询，即可生成签名的批准令牌。

⚠️ 已知的信任边界简化（生产环境必须修复）

1. 由 Agent 自行声明 human_approved 已解决（v3）：人工批准现在使用签名批准令牌（approval.py）——ASK 会返回一个绑定到精确付款意图的质询；用户的设备会对其签名；网关会验证签名、逐字段匹配意图，并防止 nonce 重放。旧版自行声明路径仍保留，但标记为 approve(legacy-deprecated)。
2. MCP 层拦截仅供参考——Agent 框架可以绕过网关，直接与钱包通信。缓解措施：配合 x402 的原生钩子使用（见 demo/demo_real.py 中的演示；该钩子在 SDK 内部、签名前触发）。最终目标：将策略的确定性部分编译到智能合约钱包模块中，并在结算层强制执行。
3. 语义检测基于正则表达式——生产环境应改用 LLM 评估并锚定意图。
4. 锚定默认写入本地日志——真实合约（contracts/PolicyAnchor.sol）和 web3 客户端（chain_anchor.BaseSepoliaAnchor）已就绪；设置 chain_config.json 即可切换到真实链（通过 Remix 部署，并使用测试 ETH）。

经济模型：评估 API 本身也是 x402 商户

分级定价：

操作	价格
确定性评估（/evaluate/basic）	免费
语义评估（/evaluate/semantic）	每个 Agent 有 100 次免费调用；之后每次调用收费 $0.003 USDC（真实 x402 费用）
策略锚定 / 撤销	免费（撤销永远免费——这是安全红线）

开放核心：此仓库中的客户端、评估引擎和演示均采用 Apache-2.0 许可证。托管评估服务（分级定价、免费额度核算、收入账本）运行于私有的 boundra-ops 仓库。

已验证 / 尚未验证

已验证（test_product.py 的全部 22 项断言和 test_mcp_client.py 均通过）： 4 层策略叠加（平台红线 × 用户 × Agent × Mandate），并采用最严格规则优先；签名批准令牌（有效令牌通过、伪造令牌被拒、意图重新绑定被拒、重放被拒）；Mandate 单次使用；撤销默认拒绝，签名 v2 可恢复；模板渲染和编译；所有 MCP 工具均通过线路测试；在真实 x402 402 往返流程中，网关会在 SDK 签名前拦截注入攻击；完整的分级定价流程——先在 Base Sepolia（2026-10-16）验证，随后在 **Base 主网（2026-10-21）**验证：免费层通过，付费层实际结算 $0.003 USDC（买方余额从 1.010 降至 1.007，平台地址收到 0.003），dogfood 钩子自行评估，语义层拦截注入攻击，并生成 /revenue 账本条目。 主网结算交易可公开验证：0xf04d3497…4eac7e5 ——实时 API 现在通过 Coinbase 的 CDP facilitator 在 Base 主网上结算。 早期测试网凭证：0x5ad8ef4b…c474bbe （托管服务代码按设计保持闭源——区块链是凭证。）

尚未验证：真实的链上锚定（合约已就绪，但部署需要测试 ETH）；真实用户需求；在真实 LLM 行为分布下语义层的误报率。