PetaSats

PetaSats MCP

通过本地、非托管的 MCP 服务，在 AI 应用中使用 Base 上的 USDC 购买 BSV。

功能介绍

PetaSats 仅支持将 Base 上的 USDC 兑换为 BSV。密钥在你的设备上生成并保存在本地。

1. 你将 USDC 锁定在 Base 上的兑换合约中。
2. 做市商锁定 BSV。
3. 工具通过默克尔证明和区块头验证锁定，然后领取 BSV 并公开密钥。
4. 做市商使用该密钥领取 USDC。

兑换金额约为 5 到 100 美元。每位买家每天最多可进行 3 笔兑换，金额不超过 200 美元；同时还受共享每日总额限制。默认采用标准速度，等待 1 次 BSV 确认。只有双方同意时，明确请求 speed: "fast" 才可缩短等待时间，且金额不得超过 25 美元。

安装并连接

使用 Node.js 22 或更高版本。建议固定使用 [email protected]。

claude mcp add petasats -- npx -y petasats-mcp

Claude Desktop（claude_desktop_config.json）、Cursor（~/.cursor/mcp.json）：

{"mcpServers":{"petasats":{"command":"npx","args":["-y","petasats-mcp"]}}}

VS Code（.vscode/mcp.json）：

{"servers":{"petasats":{"type":"stdio","command":"npx","args":["-y","petasats-mcp"]}}}

Codex（命令行、IDE 扩展或应用）：

codex mcp add petasats -- npx -y petasats-mcp

任何能够启动本地 stdio 服务的客户端都可以使用命令 npx 和参数 -y petasats-mcp。首次启动时会在 ~/.petasats 中创建密钥；PETASATS_HOME 可更改该位置。请备份 keys.json：这是唯一副本。每个工具目录只能运行一个副本，因为两个副本使用同一组密钥时，可能会分别签署对方无法看到的 Base 付款。

为工具充值

wallet_info 会显示 Base 地址。向该地址发送 Base 上的 USDC，并转入少量 ETH 用于支付 Gas；0.0002 ETH 足以支付多笔兑换的 Gas。

使用方法

询问：“购买 20 美元的 BSV 并发送到 1...”

工具	是否会转移资金
get_quote	否
swap_asset_to_bsv	是
wait_for_swap	否
swap_status	否
wallet_info	否
stop_spending	否
withdraw_bsv	是
withdraw_base	是
fund_wallet	否 — 仅规划 USDC 到 BSV 的兑换并返回报价
list_liquidity	否

你可控制的限制

你可以创建 ~/.petasats/limits.json，限制 AI 可以向哪些地址发送资金，以及每天（UTC）可以兑换的金额：

{
  "format": "petasats.limits/1",
  "bsvDestinations": ["1BoatSLRHtKNngkdXEeobR76b53LETtpyT"],
  "baseDestinations": ["0x1111111111111111111111111111111111111111"],
  "maxSwapUsdPerDay": 50,
  "allowFastSettlement": false
}

请确保该文件仅对你的用户帐户开放：chmod 600 ~/.petasats/limits.json。如果其他用户可以读取或写入限制文件，工具将拒绝使用该文件。每次资金操作前都会重新读取文件。如果操作被拒绝，提示会说明是你的限制文件拒绝了操作，并且没有发送任何资金。使用 npx petasats-mcp limits 查看限制。

stop_spending 会立即停止新的兑换和提现。只有你可以使用 npx petasats-mcp resume 恢复；已开始兑换的恢复流程仍会继续运行。

allowFastSettlement: false 会禁止新兑换使用快速结算。如果缺少此字段，则允许协商明确请求的快速兑换；默认仍采用标准结算。

这些控制措施可防范只能使用工具的 AI。能够运行 shell 命令或编辑文件的 AI 应用，也可以编辑 limits.json 或 STOP。

进度与报告

服务会为 AI 提供操作指南。有人监看时，每个阶段会报告一行，并在最后给出包含交易 ID 的摘要。对于程序，只返回结果。报告不会拖延兑换，兑换开始后也不会要求确认。

安全模型

资金只能发送到 Base 上的兑换合约、工具自身的地址或你提供的地址。工具会在公开密钥前进行验证。锁定后，做市商的 BSV 最迟可在约 4 小时（24 个区块）后退回；如果兑换未完成，你的 USDC 会在约 16 小时后退款。重启后可继续恢复流程。一次只运行一笔兑换，并在兑换期间保持服务运行。

快速模式会让工具在 BSV 锁定尚未确认时公开密钥。如果做市商对该锁定进行双花，你可能会损失兑换金额。只有双方同意且金额不超过 25 美元时，才可使用快速模式；否则兑换会等待 1 次 BSV 确认。快速模式必须由买家明确选择；省略 speed 时使用标准结算。

费用

get_quote 会显示费率以及与市场中间价的比较。你需要支付以 ETH 计价的 Base Gas、BSV 领取费，以及使用 deliver_to 时的一小笔额外 BSV 费用。协议费用请参阅 get_quote。

验证你运行的内容

npm 包由 GitHub Actions 根据带标签的提交构建，并通过 npm provenance 发布。运行 npm audit signatures；npm 页面会将构建关联到对应的提交和工作流运行记录。dist/petasats-mcp.mjs 未经过压缩。每次发布时，src/ 下的源代码都会从开发仓库导出，移除内部开发注释并将内部名称替换为中性名称；除此之外，内容完全相同。

文件、状态和恢复

该工具包使用 ~/.petasats。运行 npx petasats-mcp status 查看状态，中断后运行 npx petasats-mcp recover 恢复。

待处理的 Base 提现（例如因费用上涨而待处理）会原样重新发送；在其确认之前，新的兑换和 Base 提现都会等待。运行 npx petasats-mcp withdrawals 列出待处理的提现。如果已最终确认的 nonce 已被消耗，但找不到其收据，请在 Base 浏览器中检查该交易，然后使用 npx petasats-mcp withdrawal <hash> sent 或 npx petasats-mcp withdrawal <hash> not-sent 明确记录结果。

在一小时内重复发起相同的 Base 提现（资产、金额和地址均相同）会被拒绝，因为系统会将其视为可能的重试。同一时间不要在同一文件夹中运行两个使用该工具包的 AI 应用。

使用 0.2.0 或 0.2.1 版本发起、但 USDC 锁定交易始终未上链的兑换，可能会停留在“Waiting for BSV lock”状态，并阻止新的兑换和提现。如果该兑换运行期间没有其他副本使用同一文件夹，请在工具包的环境中设置 PETASATS_RESOLVE_OLD_STUCK_SWAPS=1（例如，在客户端的服务条目中设置 "env":{"PETASATS_RESOLVE_OLD_STUCK_SWAPS":"1"}），然后重启工具包。随后，工具包会向自己的 Base 地址发送一笔零金额交易，确保旧的锁定交易永远无法上链；该交易最终确认后，通常在 30 分钟内，会将兑换标记为失败。使用 0.2.2 或更高版本发起的兑换无需此设置即可完成处理。

故障排除

busy、limit、rate_limited、unavailable 和 declined 表示没有锁定任何资金。如果密钥文件权限有误，请恢复为仅所有者可访问。遇到 RPC 问题时，请检查网络连接并重试。

安全、许可证和免责声明

请参阅 SECURITY.md。PetaSats 使用 Open BSV License v4；第三方声明见 THIRD_PARTY_NOTICES.md。这是实验性软件：请使用少量资金，且不提供任何担保。