Obolus

Obolus

一个为 AI Agent 提供一次性 Algorand 钱包的 MCP 服务，让它无需人工准备任何东西， 即可为 x402 资源付款。

这个名字指的是渡船人收取的渡河钱：面额小，只有一种用途，花完即止。

agent → x402_fetch(url) → 402 → sign → pay → body

x402 列出了上千种资源，却几乎没有买家——几乎所有交易量都来自少数几个钱包，而且它们运行的是脚本循环，而不是 Agent。支付通道已经存在，却无人能使用。Obolus 补上买家端：自动处理账户设置、授权、签名和资金归集，让 Agent 只需消费。

---

安装

Claude Code——插件

/plugin marketplace add inviti8/Obolus
/plugin install obolus@heavymeta

配置 MCP 服务，并添加 /obolus:fund-wallet，它了解初始化的先后顺序，以及为什么不能更改顺序。除了 uv 之外，无需预先安装任何东西——服务通过 uvx obolus mcp 启动。

其他所有情况

uv tool install obolus

CLI 应使用 uv tool install，而不是 uvx：每次调用 uvx 都会重新解析，实测比已安装的控制台脚本慢 200–400 ms。每个会话只发生一次时，这点开销微不足道，而 MCP 服务也只会产生这一次开销——这就是上面的插件使用 uvx 的原因。但对于在循环中调用的命令，这并不是合适的选择。pipx install obolus 也可以。

手动添加到 Claude Code

claude mcp add obolus -e OBOLUS_NETWORK=testnet -- obolus-mcp

添加到其他任何 MCP 客户端

{
  "mcpServers": {
    "obolus": {
      "command": "obolus-mcp",
      "env": { "OBOLUS_NETWORK": "testnet" }
    }
  }
}

默认从测试网启动。 主网功能不会被禁用——Obolus 的设计目的就是完成真实付款——但如果忘了选择网络，绝不会默认使用主网。

---

为钱包注资

新金库中没有任何资金，且链上操作顺序不可更改：

obolus vault          # says which of the three steps you are on
obolus vault qr       # scannable codes for the two things you can send

#	步骤	由谁执行
1	向金库发送 ≥ 0.21 ALGO	你
2	将金库授权为 USDC 资产持有者（obolus vault optin）	Obolus
3	发送 USDC	你

先执行步骤 3、再执行步骤 2 会失败。 Algorand 账户无法接收尚未授权持有的资产——转账会被直接拒绝，不会进入待处理状态。这就是二维码中包含资产 ID 而不只是地址的原因，也是 wallet_funding_info 每次都会告知你当前所处步骤，而不只在出错时提示的原因。

二维码不包含金额。你需要在自己的钱包中输入金额，并在确认前查看。

---

使用方法

刻意只提供三个工具：

工具	功能
x402_fetch	获取 URL；如果响应为 402，则付款。返回响应正文。
wallet_status	余额、当前会话、今日支出和限额。
wallet_funding_info	如何转入资金。供人使用，而非供 Agent 使用。

没有针对特定商家的工具。所有资源都通过 x402_fetch 获取，因为钱包一旦为某个卖家添加专用操作，就不再是钱包了。

---

如何限制损失

会话余额由链强制执行。 付款来自短期会话账户，该账户由你的金库注资，而非直接从金库付款。会话账户无法花费其未持有的资金，无论这里的任何代码如何运行，这一点都成立。

其他限制均在进程内执行，可在数据目录中的 config.toml 配置：

[caps]
session_balance_micro = 5000000   # $5 per session
per_call_micro        = 500000    # $0.50 per call
daily_micro           = 2000000   # $2 a day, resets 00:00 UTC
allowlist             = []        # payTo addresses or hostnames; empty = any

[session]
idle_timeout_seconds  = 600       # close and sweep back after this

[files]
# root = "/path/you/choose"       # off unless set - see Safety

有些拒绝规则并非限额，也没有对应的配置项：向我们控制的地址付款、在主网上访问非 https 资源、使用钱包未持有的资产付款，以及处理格式不正确的 x402 v2 402 挑战。

---

安全

助记词是找回资金的唯一途径。 它保存在你的数据目录中。将 OBOLUS_DATA_DIR 指向新位置会创建一个新钱包，而不是迁移旧钱包。请备份该目录。

默认关闭文件访问。 x402_fetch 可以将文件发送到收费端点，并将响应写回，这样你就可以获取已签名的图像或经过处理的文档。除非设置 [files] root，否则这两项功能都会被禁用；设置后，文件访问也仅限于该目录。这是有意为之：将字节数据移出你的设备，并非支出上限能够约束的行为。

审批针对的是工具，而非每笔付款。 大多数 MCP 客户端只会询问一次并记住你的选择。这意味着上述上限才是实际的支出边界，而不是提示词 — 请参阅 DESIGN.md §7.1，其中记录了实际测量的结果，而非假设。

付款结算只能证明付款已结算 — 无法证明资源正确、可信或物有所值。

---

文档

• CLAUDE.md — 入门指南，以及那些需要花费大量调试时间才能了解的 x402 事实。
• DESIGN.md — 架构、安全模型，以及直言不讳列出的局限性。
• IMPLEMENTATION_PLAN.md — 构建顺序，以及每个阶段实际验证的内容。

状态

已在主网上运行。 2026-08-13 和 08-14，一名 Agent 通过 MCP 使用 Obolus，向一家在线商户购买了三项资源，并用真实 USDC 支付 — 一次公证服务，费用为 $0.05；第二次公证服务，费用为 $0.05；以及对一份 13 MB TIFF 文件进行 C2PA 签名，费用为 $0.15。每笔付款都来自一个一次性会话账户，该账户经过派生、注资、消费后关闭并清空；两个会话均已对账，没有遗留资金。按设计，三笔款项都已结算，且 fee: 0，手续费由 Facilitator 赞助。

这证明了支付通道从头到尾都能正常工作：一个无需人工介入的 Agent 持有密钥、响应 402 并获得了字节数据。但这并不代表这些资源物有所值 — 结算只能证明付款已结算，除此之外什么也证明不了。

测试网仍是默认网络，也是开发环境。主网受到保护，但从未被禁用。