核心功能
sparkbtcbot-proxy 是一个部署于Vercel的无服务器HTTP API代理层，解决AI Agent直接持有比特币钱包私钥的安全隐患。它通过Bearer Token认证机制，为Agent提供非托管、有权限边界的Spark Bitcoin L2网络访问能力。
关键能力矩阵
| 功能模块 | 支持操作 | 所需角色 |
|---------|---------|---------|
| 账户信息 | 余额查询、钱包地址、交易历史、手续费估算 | 任意角色 |
| 收款服务 | 创建BOLT11闪电发票、Spark地址收款 | `admin`/`invoice` |
| 支付服务 | 支付闪电发票、链上转账、L402付费墙内容获取 | `admin`/`pay-only` |
| 代币管理 | 创建/撤销子Token、查看访问日志 | `admin`专属 |
| L402集成 | 自动处理402付费墙协议，支持异步支付轮询 | `admin`/`pay-only` |
架构优势
相比直接集成Spark SDK，代理模式的核心价值在于安全隔离与合规管控：
- 私钥不出库：助记词由服务端托管，Agent仅持Token
- 即时权限回收：泄露Token可直接撤销，无需转移资金
- 消费硬上限：支持单笔/日限额双重控制，防超额支出
- 审计可追溯：完整操作日志，便于合规审查
技术实现细节
API采用RESTful设计，所有请求需携带Authorization: Bearer <token>头。特别值得注意的是L402异步支付处理——闪电网络支付存在确认延迟，当7.5秒内未获得preimage时返回pending状态，开发者必须实现轮询逻辑（建议间隔3秒，最多10次），否则将面临"已扣款但未获取内容"的资金损失风险。
Token角色设计遵循最小权限原则：read-only仅查询，invoice仅收款，pay-only仅付款，admin拥有完整管控权。创建子Token时可叠加maxTxSats和dailyBudgetSats限额，与全局环境变量取交集生效。
局限与注意事项
1. 网络依赖性：作为HTTP代理，无法离线签名，完全依赖服务端可用性
2. 托管信任假设：需信任proxy部署方的私钥安全管理能力
3. Vercel冷启动：无服务器架构存在首请求延迟，高频场景需考虑预热策略
4. L402实现复杂度：异步状态机增加了集成成本，新手易遗漏轮询逻辑导致资金损失
5. 生态局限性：Spark Bitcoin L2为相对新兴的侧链方案，流动性与商户接受度不及主网
适用场景
- 多Agent共享钱包的权限隔离场景
- 需要审计日志的企业级支付自动化
- 对私钥泄露极度敏感的生产环境
- L402协议的内容付费网关集成
- 需要快速撤销访问权限的临时授权场景
不适合场景
- 需要离线签名的边缘计算环境
- 追求极致去信任化的自我托管方案
- 高频微支付（受限于HTTP往返+冷启动延迟）
- 主网比特币原生操作（Spark为L2方案）
风险评估
| 风险类型 | 等级 | 说明 |
|---------|------|------|
| 私钥泄露 | 低 | 服务端托管，但代码开源可审计 |
| Token泄露 | 中 | 泄露后资金受限于角色和限额，可撤销 |
| 服务中断 | 中 | 依赖Vercel和Spark网络稳定性 |
| 资金损失 | 中 | L402异步逻辑实现不当导致重复扣款或丢单 |
| 合规风险 | 低 | 完整日志支持，但需自行遵守当地加密法规 |
建议生产环境配合监控告警、Token定期轮换、限额保守设置等安全措施使用。