agent-wallet

核心用法

agent-wallet 是专为 AI 代理设计的自托管 Bitcoin Lightning 钱包，由 MoneyDevKit 开发。通过单一命令即可初始化，无需 API 密钥、注册或账户体系。核心功能包括：

• 钱包初始化：npx @moneydevkit/agent-wallet init 生成 BIP39 助记词，创建本地配置
• 余额查询：balance 返回以 satoshi 为单位的余额
• 收款：支持固定金额/可变金额发票（receive）、BOLT12 可复用报价（receive-bolt12）
• 付款：自动识别 bolt11、b bolt12、LNURL、闪电地址等多种格式
• 本地守护进程：在 localhost:3456 运行 HTTP 服务，轮询入账支付

显著优点

1. 完全自托管：私钥（助记词）仅存本地，无第三方托管风险
2. 零配置设计：一条命令启动，无需 Lightning 节点运维知识
3. 多标准兼容：覆盖 BOLT11/BOLT12/LNURL/闪电地址全生态
4. JSON 输出：所有命令返回结构化数据，便于代理程序解析
5. Agent-to-Agent 支付：代理间可直接通过对等网络完成价值转移

潜在缺点与局限性

• 安全责任自负：助记词丢失即资金永久丢失，无恢复途径
• 单点故障：本地守护进程若崩溃，支付轮询将中断
• 网络依赖：需 outbound 连接至 MDK Lightning 基础设施
• Node.js 依赖：要求目标环境预装 node/npx
• 文件系统风险：助记词明文存储于 ~/.mdk-wallet/config.json，需严格权限控制

适合人群

• 需要自主收款/付款能力的 AI 代理开发者
• 追求非托管、抗审查支付方案的自动化系统
• 已具备 Node.js 运行环境的边缘计算或服务器场景
• 愿意承担密钥管理责任的进阶用户

常规风险

| 风险类别 | 描述 | 缓解建议 |

|---------|------|---------|

| 密钥泄露 | 助记词文件权限不当或被恶意读取 | `chmod 600 ~/.mdk-wallet/` 并定期备份至离线介质 |

| 供应链攻击 | npm 包被篡改 | 生产环境锁定版本号（如 `@0.11.0`），验证源码签名 |

| 资金损失 | 误删钱包目录或助记词遗忘 | 初始化后立即离线备份助记词 |

| 网络隔离 | 守护进程无法连接 MDK 基础设施 | 监控 `status` 命令，配置防火墙放行 outbound |

| 本地端口冲突 | `:3456` 被占用 | 启动前检查端口占用，或使用容器隔离 |

核心用法

agent-wallet 是一款专为 AI 代理设计的自托管比特币 Lightning 网络钱包。通过简单的 npm 命令即可初始化，无需 API 密钥、注册或账户管理。代理完全掌控自己的私钥（BIP39 助记词），实现真正的非托管资金管理。

快速启动流程：
1. 运行 npx @moneydevkit/agent-wallet init 生成助记词并启动本地守护进程
2. 使用 balance 查看余额、receive <amount> 生成收款发票
3. 通过 send <destination> [amount] 向任意闪电地址、BOLT11/12 发票或 LNURL 付款

技术架构：

• 本地 HTTP 守护进程运行在 localhost:3456，仅绑定本地地址
• 自动连接 MoneyDevKit 的 Lightning 基础设施处理链上交互
• 每 30 秒轮询检测入账支付，无需 webhook 配置
• 所有数据持久化至 ~/.mdk-wallet/ 目录

显著优点

零配置体验：一条命令完成钱包初始化，无需复杂的 Lightning 节点搭建，代理即刻具备收发比特币能力。

全协议兼容：原生支持 BOLT11 发票、BOLT12 可复用报价、LNURL 支付和闪电地址（lightning address），覆盖 Lightning 生态主要支付场景。

代理原生设计：所有输出为结构化 JSON，便于 AI 解析处理；支持代理间直接支付（invoice/闪电地址），赋能 AI 经济自主化。

透明可控：开源代码可审计，明确披露所有网络行为和本地数据存储，符合 GDPR 透明度要求。

潜在缺点与局限性

资金安全责任：自托管意味着用户完全承担资金保护责任。助记词以明文存储于本地文件，丢失或泄露即导致资金不可恢复。

单点运行依赖：本地守护进程必须持续运行才能接收支付，进程中断期间入账可能延迟感知（依赖 30 秒轮询）。

网络与平台绑定：依赖 MDK 的 Lightning 基础设施进行链上交互；当前仅支持 Node.js 环境，需 npm/npx 可用。

功能范围专注：纯钱包功能，不包含法币兑换、多签支持或高级 Lightning 路由管理，复杂企业场景需配合其他工具。

适合的目标群体

• AI 开发者：为代理/机器人集成支付能力，实现服务自动变现或资源购买
• 自动化交易系统：需要程序化收发小额比特币的场景
• Lightning 应用原型开发：快速验证 Lightning 支付集成的 MVP 项目
• 隐私优先用户：不愿依赖托管服务、倾向自掌控资金的个人或组织

使用风险

资金安全高敏：主网真实资金风险，务必在测试环境充分验证后再投入生产；强烈建议固定 npm 版本号（如 @0.11.0）防止供应链攻击。

本地文件安全：~/.mdk-wallet/config.json 包含未加密助记词，需确保目录权限为 600，避免多用户环境使用，定期离线备份助记词。

守护进程可用性：生产环境需监控进程健康，异常终止可能导致支付处理中断；建议配合进程管理工具（如 systemd）确保服务持续运行。

依赖更新风险：自动使用 npx @latest 可能引入未测试变更，生产环境应显式锁定版本并制定升级测试流程。