BitBooth Agent Tools

@bitbooth/mcp-fetch

面向 Agent 的 x402 目录和买方，集成在一个 MCP 服务中。 免费发现并预检 BitBooth API；通过 Base USDC 获取 URL；或明确选择 XRPL 主网 RLUSD，用于 PageDelta、轻量级页面监控和 XRPL 钱包资金续航监控。

它为何值得付费： page_delta 会渲染公开页面，返回有界 Markdown 和精确的重点证据，将其与该付款方之前的观察结果进行比较，并可附带有界 JPEG 快照。它还会返回哈希、不会授权访问的不透明跟踪游标、并非公开证明的内容绑定观察 ID，以及已结算的付款元数据。网页内容始终标记为不可信。

🧭 范围： discover_bitbooth 和 preflight_bitbooth 免费，并在所有支付通道模式下均可使用，即使没有钱包凭据也一样。Base 仍是默认的付费通道，并提供 fetch。明确选择 xrpl-rlusd 模式后，将提供 0.001-RLUSD 监控工具，并保留 page_delta 以供恢复。发起新的 PageDelta 签名时，必须为每次调用明确设置至少 0.010000 的上限；上限为零、未设置或之后调低时，只允许精确恢复已签名的证明。实时目录 /bazaar.json 是权威来源。

✅ 已在链上验证 — BitBooth 的 XRPL 商户收据可在 XRPL AI 个人资料上公开查看。

🛡️ 默认使用测试网。 全新安装使用 Base Sepolia。XRPL 仅支持主网，且需要明确选择通道并单独提供 XRPL 种子。

安装

请使用 2.3.1 版本，以确保 PageDelta 配置说明准确： 此补丁修正了示例，加入 PageDelta 必需的 requestId，并准确指出默认的公共 /v1/fetch 路由使用 Base Sepolia。它不会扩展支付运行时或增加支付网络。PageDelta 仍使用 2.3.0 引入的串行 XRPL 买方。请保留下方的 ^2.3.1 固定版本，以免较旧的客户端暴露不兼容的工具契约或过时的设置说明。

原生支持 MCP——可直接接入 Claude Desktop、Claude Code、Cursor、Windsurf、Continue 或任何兼容 MCP 的客户端。 以下代码片段与 app.heinrichstech.com 上的权威安装配置一致。

Claude Desktop / Cursor / Windsurf / Continue

将以下内容粘贴到 claude_desktop_config.json（Claude Desktop）、.cursorrules.mcp.json（Cursor）或客户端的 MCP 配置中：

免费发现目录并进行预检，无需钱包：

{
  "mcpServers": {
    "bitbooth": {
      "command": "npx",
      "args": ["-y", "@bitbooth/mcp-fetch@^2.3.1"]
    }
  }
}

添加专用测试网钱包，以启用付费工具 fetch：

{
  "mcpServers": {
    "bitbooth": {
      "command": "npx",
      "args": ["-y", "@bitbooth/mcp-fetch@^2.3.1"],
      "env": {
        "BITBOOTH_AGENT_KEY": "0x<your-testnet-wallet-private-key>",
        "BITBOOTH_MAX_PER_CALL_USD": "0.10",
        "BITBOOTH_DAILY_LIMIT_USD": "1.00"
      }
    }
  }
}

Claude Code

claude mcp add bitbooth -- npx -y @bitbooth/mcp-fetch@^2.3.1

设置 Agent 钱包密钥：

export BITBOOTH_AGENT_KEY="0x<your-testnet-wallet-private-key>"

全局安装

npm install -g @bitbooth/mcp-fetch@^2.3.1
mcp-fetch   # runs on stdio

获取测试网钱包和 USDC（免费，2 分钟）

1. 生成 EVM 钱包，或使用已有且由你控制的钱包
2. 为其充值 Base Sepolia ETH（Gas）：https://www.alchemy.com/faucets/base-sepolia
3. 为其充值 Base Sepolia USDC：https://faucet.circle.com（选择 Base Sepolia）
4. 将 BITBOOTH_AGENT_KEY 设置为钱包的私钥（0x...）

用法

每次安装都会公开两个免费工具，它们绝不会签署或提交付款：

discover_bitbooth(
  query: "repair malformed JSON",
  category: "utility",
  maxPriceUsd: 0.01,
  network: "eip155:8453",
  limit: 10
)

preflight_bitbooth(
  route: "json-repair",
  maxPriceUsd: 0.01,
  network: "eip155:8453"
)

discover_bitbooth 会获取并验证实时目录，然后返回包含匹配路由和所公布付款要求的简洁 JSON。设置 configuredOnly: true 可按 MCP 服务配置的网络和资产筛选，而不是浏览所有支付渠道。

preflight_bitbooth 接受精确的路由名称、路径或 URL，并会在硬性价格上限内选择一项兼容的已公布要求；如果没有匹配项，则返回结构化的 no_match。如果明确指定了 network 或 asset，则以该筛选条件为准，但它不会重新配置买方：所选要求仍必须与服务配置的支付渠道匹配。否则，预检会自动使用该服务配置的支付渠道。其输出始终包含 paymentAuthorized: false。买方仍必须将所选要求与实时 HTTP 402 挑战进行比较，然后再签署。

配置好 Base 钱包后，Agent 还会获得付费 fetch 工具：

fetch(url: "https://example.com", mode: "full")

模式：

模式	价格	说明	最适用场景
fast	0.005 USDC	将原始 HTML 转换为 markdown	快速查询、静态页面
full	0.005 USDC	提取文章（Readability），然后转换为 markdown	博客文章、文档、新闻

返回包含标题、正文和元数据（URL、时间戳、内容长度、截断状态）的 markdown。

XRPL RLUSD Agent 工具

XRPL 模式会用两个价格为 0.001 RLUSD 的监控工具替代付费 fetch 工具。每次调用明确设置的上限至少为 0.010000 时，还会公开 PageDelta。免费发现和预检工具仍可用：

watch_page(url: "https://example.com/pricing")

watch_xrpl_wallet(
  address: "rAgentWallet...",
  minCallsRemaining: 10,
  minSpendableXrpDrops: "1000",
  allowedDestinations: ["rKnownMerchant..."]
)

page_delta(
  requestId: "2f019f98-7bea-4c44-9b3f-2d6d9ffbce6c",
  url: "https://example.com/pricing",
  extract: "article",
  focus: "Enterprise price",
  cursor: "pd1_<cursor-from-the-prior-observation>"
)

watch_page 会存储轻量级内容指纹，并在后续调用时报告有意义的变化。watch_xrpl_wallet 会返回 OK、WARN 或 CRITICAL，并提供扣除储备后的可支用 XRP、RLUSD 信任线和付费调用余量、近期已验证活动、陌生收款地址，以及按付款方划分的基线变化。省略的监控策略字段会使用服务器默认值：每次计划调用 0.001 RLUSD、剩余 10 次调用、1,000 可支用 drops、没有已知地址，以及最近 50 笔交易。

page_delta 的费用固定为 0.010000 RLUSD。它要求调用方生成 UUID requestId；仅当需要恢复同一次付费尝试时才重复使用该 UUID。开始后续观察之前，请使用新的 UUID，并将 acknowledgeRequestId 设为之前已完成的 UUID。其 extract 值为 article（默认值）或 raw；focus 是可选项，用于在有界 Markdown 中进行区分大小写的精确搜索；cursor 则是之前观察返回的不透明值。缺少截图也是有效结果，具体情况会在 warnings 中说明。

如需启用，请使用专用的低余额付款钱包，其中仅存放计划供此 Agent 使用的 RLUSD 和 XRP 燃料预算：

{
  "mcpServers": {
    "bitbooth-watch": {
      "command": "npx",
      "args": ["-y", "@bitbooth/mcp-fetch@^2.3.1"],
      "env": {
        "BITBOOTH_PAYMENT_RAIL": "xrpl-rlusd",
        "BITBOOTH_XRPL_SEED": "sEd<dedicated-agent-seed>",
        "BITBOOTH_MAX_PER_CALL_USD": "0.010000",
        "BITBOOTH_DAILY_LIMIT_USD": "0.10"
      }
    }
  }
}

这会产生真实的主网支出。BITBOOTH_AGENT_KEY 绝不会用作 XRPL 种子；仅设置 BITBOOTH_XRPL_SEED 不会启用 XRPL 付款。如果 Agent 只应拥有监控工具，请保留 BITBOOTH_MAX_PER_CALL_USD=0.001；此时不会注册 PageDelta。监控付款钱包本身虽可行，但该钱包自身的监控付款会改变钱包状态；为获得更清晰的事件信号，请使用另一个低余额看门狗钱包付款。

定价

项目	费用
discover_bitbooth	免费 — 读取公开的实时目录
preflight_bitbooth	免费 — 选择一项需求，但不会签名或付款
fast/full	每次获取 0.005 USDC
watch_page	每次指纹比较 0.001 RLUSD
watch_xrpl_wallet	每次钱包可用时长/活动检查 0.001 RLUSD
page_delta	每次渲染观测和比较 0.010000 RLUSD
Gas	按需支付 Base Gas；XRPL 费用默认上限为 100 drops
默认链	Base Sepolia（测试网）。主网需明确选择加入。

配置

环境变量	说明	默认值
BITBOOTH_AGENT_KEY	专用 EVM Agent 私钥（仅付费的 Base fetch 工具需要）	—
BITBOOTH_PAYMENT_RAIL	base 或明确选择加入主网的 xrpl-rlusd	base
BITBOOTH_XRPL_SEED	专用 XRPL 种子；仅 xrpl-rlusd 需要	—
BITBOOTH_CHAIN_ID	旧版 fetch 工具使用的 Base 网络。默认公共 /v1/fetch 源当前要求使用 84532（Base Sepolia）。	84532
BITBOOTH_API_URL	BitBooth 网关 URL	https://app.heinrichstech.com
BITBOOTH_RPC_URL	EVM RPC 端点	https://base-sepolia-rpc.publicnode.com
BITBOOTH_CONFIRMATIONS	重试前等待的交易确认数（至少为 2）	2
BITBOOTH_API_KEY	可选的租户 API 密钥（用于提高速率限制）	—
BITBOOTH_MAX_PER_CALL_USD	单次挑战可接受的最高稳定币金额；若要启用 PageDelta，必须明确设为至少 0.010000	0.10 Base / 0.001 XRPL
BITBOOTH_DAILY_LIMIT_USD	每个钱包每日（UTC）的预留额度上限；XRPL 记账在重启后仍会保留	1.00 Base / 0.10 XRPL
BITBOOTH_XRPL_WS_URL	仅用于自动填充已签名交易并将其绑定到账本的免凭据 WSS 端点	wss://xrplcluster.com/
BITBOOTH_XRPL_MAX_FEE_DROPS	自动填充交易允许的最高 XRP 网络费用	100

Base 网络兼容性

仅当 BITBOOTH_API_URL 指向一个兼容的 x402 来源，且该来源确实在 Base 主网上发起挑战时，旧版 Base 客户端才支持链 ID 8453。默认的公共 https://app.heinrichstech.com/v1/fetch 路由目前会在 Base Sepolia（84532）上发起挑战；如果挑战的网络与配置不符，客户端会有意拒绝该挑战。

请勿在默认来源上设置 BITBOOTH_CHAIN_ID=8453。本软件包中 BitBooth 当前的 PageDelta 主网路径采用上文明确指定的 xrpl-rlusd 配置。

XRPL 安全限制

XRPL 模式只有在每个实时 PAYMENT-REQUIRED 挑战都符合以下所有值时，才会付款：

• HTTPS 来源 https://app.heinrichstech.com
• 网络 xrpl:0、方案 exact，以及采用规范十六进制编码的 RLUSD 货币
• Ripple RLUSD 发行方 rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De
• BitBooth 收款方 rfryheo6yzFdLWj8qUQtZc7zG9MKkBkUEy
• 完全匹配的所请求资源 URL、有时限的一次性发票，以及预期的来源标签
• 任一 XRPL 监视工具的金额必须恰好为 0.001000 RLUSD
• 现有 /v1/cdp/render-pro 资源中 PageDelta 的金额必须恰好为 0.010000 RLUSD

交易受最后账本限制，禁止部分付款，并且在签名前会再次检查自动填充的收款方、金额、发行方、发票、备注和手续费字段。已签名的载荷会以 PAYMENT-SIGNATURE 发送；载荷和种子绝不会打印出来。

watch_page 在请求挑战前会拒绝包含凭据的 URL、localhost 和 .local 名称，以及字面上的私有、环回或链路本地 IP。BitBooth 也会在服务端解析并检查 DNS，然后进行结算，以防范 DNS 重绑定和主机名解析到私有地址的情况。watch_xrpl_wallet 在请求挑战前会验证传统地址、数值范围、活动上限，以及最多 25 个地址的允许列表。

程序化使用

无需构造钱包客户端即可进行目录发现和预检：

import { createCatalogClient } from '@bitbooth/mcp-fetch/catalog-client';

const catalog = createCatalogClient({ chainId: 8453 });
const choices = await catalog.discover({ query: 'monitor', maxPriceUsd: 0.01 });
const checkout = await catalog.preflight({ route: 'web-watch', maxPriceUsd: 0.001 });
console.log(choices.resources, checkout);

自动付款：

import { createX402Client } from '@bitbooth/mcp-fetch/x402-client';

const client = createX402Client({ agentKey: process.env.AGENT_KEY });
const result = await client.fetchWithPayment('https://example.com', 'fast');
console.log(result.markdown);

const watcher = createX402Client({
  paymentRail: 'xrpl-rlusd',
  xrplSeed: process.env.DEDICATED_XRPL_AGENT_SEED,
  maxPerCallUsd: '0.010000',
  dailyLimitUsd: '0.10',
});
const result = await watcher.watchPageWithPayment('https://example.com/pricing');
console.log(result.changed, result.hashes.current, result.baseline);

const health = await watcher.watchXrplWalletWithPayment({
  address: 'rAgentWallet...',
  minCallsRemaining: 10,
  minSpendableXrpDrops: '1000',
  allowedDestinations: ['rKnownMerchant...'],
});
console.log(health.status, health.runway, health.alerts);

const firstRequestId = crypto.randomUUID();
const observation = await watcher.pageDeltaWithPayment({
  requestId: firstRequestId,
  url: 'https://example.com/pricing',
  extract: 'article',
  focus: 'Enterprise price',
});
console.log(observation.diff, observation.focusEvidence, observation.payment);

const nextObservation = await watcher.pageDeltaWithPayment({
  requestId: crypto.randomUUID(),
  acknowledgeRequestId: firstRequestId,
  url: 'https://example.com/pricing',
});

工作原理

免费目录客户端会执行一次无需凭据的 GET /bazaar.json，使用 Zod 验证完整的远程载荷，并在本地筛选。它不会发送 API 密钥、钱包密钥、种子、签名或支付标头。预检仅供参考：最终买方仍必须重新验证最新的 HTTP 402 挑战。

对于 Base 支付，软件包会执行现有的请求绑定式 USDC 转账流程。在 XRPL 模式下，它会读取 base64 编码的 PAYMENT-REQUIRED v2 标头，精确选择一个固定的 RLUSD 支付要求，检查路由的精确规范价格，持久化预留支出，然后才签署绑定发票的 XRPL Payment 并发送 base64 编码的 PAYMENT-SIGNATURE。PageDelta 使用同一代码路径，而非另一个签名器或支付循环。整个 XRPL 生命周期按钱包串行处理，包括跨软件包客户端和进程的情况。每个钱包最多保留一个未解决的证明；针对同一请求的重试会逐字节复用该证明，而不同请求在第一个请求解决前会被阻止。page_delta 要求调用方生成 UUID requestId：仅在恢复同一次已支付尝试时复用它。经验证的结果会一直保留，直到下一次 PageDelta 调用提供新的 UUID，并将 acknowledgeRequestId 设为前一个 UUID。确认操作和下一次预留是钱包文档中的一次原子状态转换。自动监控结果无需 ID，始终保持最新状态，且不会覆盖尚未确认的显式 PageDelta 结果。

XRPL 证明、有界的已完成结果和每钱包 UTC 日支出账本会使用专用钱包种子派生的密钥，一同加密存储在每钱包文档中。文档会执行 fsync 并以原子方式替换；POSIX 所有权／模式和 Windows 私有 DACL 回读均采用失败关闭策略。 仅当 MCP 主机需要使用其他持久化状态目录时，才设置 BITBOOTH_XRPL_JOURNAL_DIR。重启后，请使用完全相同的 requestId 和输入重试。切勿仅为绕过阻止而删除此状态。由运行中进程持有的租约不会被抢占；原生 HTTP 调用最长持续 30 秒，若主机确实卡死，必须先终止主机，才能通过 PID 恢复。

零人工介入。零注册。只需通过 x402 按次支付。

我的 Agent 可以调用哪些端点

每种模式都会提供 discover_bitbooth 和 preflight_bitbooth。付费工具的提供情况取决于所选支付通道：Base 上提供 fetch；XRPL RLUSD 上提供 watch_page、watch_xrpl_wallet 和支持恢复的 page_delta。PageDelta 只有在单次调用明确设置至少为 0.010000 的上限时，才会开始新支出。Agent 可以通过兼容 x402 的买方使用普通 HTTP 调用 BitBooth 的其余功能。价格和路由库存会变化，因此 /bazaar.json 和最新的 HTTP 402 挑战是权威依据。

联邦采购资质

BitBooth 由一家通过 SDVOSB 认证的残障退伍军人所有小型企业运营，拥有有效的 CAGE 代码和 SAM.gov 注册。国防和联邦承包商团队可以通过一家可识别的美国供应商采购实施和托管运营支持。详情请见落地页。

安全说明

• BITBOOTH_AGENT_KEY 和 BITBOOTH_XRPL_SEED 都是机密。请使用单独的专用 Agent 钱包，切勿使用个人钱包或金库钱包。
• 仅用于发现的安装无需任何机密。目录客户端绝不会将 BITBOOTH_API_KEY 或任何支付凭证转发到 /bazaar.json。
• 默认配置使用 testnet。切勿在 testnet 配置中设置 mainnet 密钥。
• Base 会根据每个支付挑战验证收款方；所有 XRPL 工具都会在代码中固定规范网络、发行方、商户、资源和特定路由的价格。如果结算后交付失败，XRPL 凭证会保留以供安全重试；请使用完全相同的工具请求重试，切勿手动再次提交付款。
• Base 的支出预留仅在进程内有效。XRPL 预留和已确认总额还会在签名之前持久化到每个钱包按 UTC 日划分的加密账本中，因此进程重启不会重置配置的 XRPL 每日限额。只有在收到与正文和标头绑定的明确未结算响应后，已签名的预留才会释放。如果挑战过期或当前上限撤销了未签名的预留，则会以原子方式释放该预留。
• 如果仅删除或损坏文档，加密文档和私有目录会以失败关闭方式处理。拥有相同 OS 账户的恶意用户仍可删除或回滚所有本地状态；若不创建另一个可能出现脑裂的状态存储，纯本地日志无法区分这种情况与首次使用。请将本地账户视为可信，并刻意将专用 Agent 钱包的余额保持在较低水平——链上钱包余额就是损失上限。

许可证

MIT