比特币钱包代理服务

sparkbtcbot代理

一个无服务器代理，允许AI代理使用 火花 基于HTTP的比特币L2钱包，不暴露私钥。

火花 是一种比特币L2，具有即时支付和亚satoshi费用。此代理将Spark SDK封装在经过身份验证的REST端点后面，因此代理可以检查余额、发送付款和创建发票，同时确保助记词在服务器上的安全。

为什么要用这个？

如果您授予代理直接SDK访问权限(火花球技能)，代理人持有你的助记符。这对测试来说很好，但在生产中有风险。

此代理解决了以下问题：

• 记忆留在服务器上 --代理获得的是承载令牌，而不是密钥
• 支出限额 --每笔交易和每日支出的上限（全球或每个代币）
• 可撤销访问 --在不转移资金的情况下切断一个受影响的代理人
• 基于角色的身份验证 --如果代理人不需要花钱，只给他们发票访问权限
• L402支架 --自动支付Lightning付费墙并获取受保护的内容

令牌角色

这 API_AUTH_TOKEN env-var是一个硬编码的管理回退——即使Redis宕机，它也总是有效的。使用它来引导：通过API创建作用域令牌，然后将这些令牌交给代理。

API

所有路线都需要 Authorization: Bearer <token>.

笔记：

• POST /api/pay, POST /api/transfer, POST /api/l402，以及 GET /api/l402/status 需要 admin 或 pay-only 令牌
• POST /api/invoice/create 和 POST /api/invoice/spark 需要 admin 或 invoice 令牌
• 代币管理路线(/api/tokens)要求a admin 令牌
• 只读路线(/api/balance, /api/info等）与任何角色合作
• POST /api/l402/preview 与任何角色合作（不花钱）

示例：创建发票

curl -X POST https://your-deployment.vercel.app/api/invoice/create \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"amountSats": 1000, "memo": "Test invoice"}'

退货：

{"success": true, "data": {"encodedInvoice": "lnbc10u1p..."}}

示例：L402付费墙

L402 让代理使用Lightning为API访问付费。代理处理整个流程：检测402、支付发票、获取预映像、使用身份验证重试。

curl -X POST https://your-deployment.vercel.app/api/l402 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://lightningfaucet.com/api/l402/joke"}'

退货：

{
  "success": true,
  "data": {
    "status": 200,
    "paid": true,
    "priceSats": 21,
    "preimage": "be2ebe7c...",
    "data": {"setup": "What's a programmer's favorite hangout?", "punchline": "Foo Bar!"}
  }
}

预览L402成本

在付款之前，您可以查看L402受保护资源的成本：

curl -X POST https://your-deployment.vercel.app/api/l402/preview \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://lightningfaucet.com/api/l402/joke"}'

退货：

{
  "success": true,
  "data": {
    "requires_payment": true,
    "invoice_amount_sats": 21,
    "invoice": "lnbc210n1p...",
    "macaroon": "AgELbGlnaHRuaW5n..."
  }
}

如果资源不需要付款（非402响应），您将得到 requires_payment: false 与响应数据。

处理待处理的L402付款

通过Spark进行闪电支付是异步的。如果支付成功，但预映像在超时窗口（约7.5秒）内不可用，代理将返回 pending 状态而不是失败：

{
  "success": true,
  "data": {
    "status": "pending",
    "pendingId": "a1b2c3d4...",
    "message": "Payment sent but preimage not yet available. Poll GET /api/l402/status?id=<pendingId> to complete.",
    "priceSats": 21
  }
}

特工必须处理这个案子。 当你收到 status: "pending":

1. 等待2-5秒
2. 呼叫 GET /api/l402/status?id=<pendingId>
3. 如果仍未完成，请重复步骤1-2（总共约30秒）
4. 完成后，您将获得受保护内容的完整响应

# Poll for completion
curl "https://your-deployment.vercel.app/api/l402/status?id=a1b2c3d4..." \
  -H "Authorization: Bearer $TOKEN"

挂起状态以1小时的TTL存储在Redis中。如果您不在该窗口内轮询，则挂起的记录将过期，您需要发出新的L402请求（将再次支付）。

对于代理开发人员来说很重要： 您的代理逻辑应该包括L402请求的重试循环。付款已发送——未进行投票意味着您已付款，但未收到内容。

令牌缓存

L402令牌按域缓存并自动重用。当您向已付费的域发出请求时，代理会首先尝试缓存的令牌。如果它仍然有效，您将无需再次付费即可获得内容。如果服务器返回402（令牌过期），则代理支付新令牌并缓存它。

回应包括 cached: true 当使用缓存令牌时：

{
  "success": true,
  "data": {
    "status": 200,
    "paid": false,
    "cached": true,
    "data": {"setup": "...", "punchline": "..."}
  }
}

令牌将被缓存长达24小时（或直到服务器拒绝它们）。

自动重试空响应

一些L402服务器在支付后立即返回空内容（它们可能尚未处理预映像）。如果响应看起来为空，代理会自动重试最终获取最多3次，延迟200毫秒。这涵盖了受保护内容具有空字段的情况（例如。， {"setup": null, "punchline": null})或者完全是空的。

环境变量

入门

你需要一个 维塞尔 帐户（免费版有效）和 升级Redis 数据库（免费层有效）。

选项1——作为Claude Code插件安装（用于使用部署的代理）

如果你的目标是让代理访问已经存在的代理（你的或其他人的），请通过Claude Code插件系统安装该技能：

claude plugin marketplace add https://github.com/echennells/sparkbtcbot-proxy
claude plugin install sparkbtcbot-proxy

它将此回购注册为市场，并安装API使用技能和部署技能。然后，代理可以使用以下命令调用代理 PROXY_URL 和 PROXY_TOKEN env变量集。

选项2——克隆并部署您自己的代理

git clone https://github.com/echennells/sparkbtcbot-proxy.git
cd sparkbtcbot-proxy
npm install
npx vercel --prod

在Vercel仪表板中设置环境变量，然后重新部署。

有关详细的分步说明（包括生成助记符和通过API创建Redis数据库），请参阅 skills/deploy/SKILL.md该文件也是上述Claude插件的一部分，因此安装的代理可以为您驱动部署。

另见

火花球技能 --允许代理直接访问Spark SDK。更简单（无服务器），但代理持有助记符，并且没有支出限制。