什么是 Spark Bitcoin L2 代理部署器？

Spark Bitcoin L2 代理部署器是 Openclaw Skills 库中的一个专门工具，旨在连接 AI 代理与比特币闪电网络。它作为一个部署在 Vercel 上的无服务器中间件，充当保护层，允许代理在不暴露主助记词的情况下执行浅包操作。通过使用此技能，开发者可以实现粒度化的安全控制，包括单笔交易支出上限和每日预算。

该架构利用 Upstash Redis 进行无状态会话管理、日志记录和令牌存储，确保您的 AI 驱动的财务操作保持稳健且可审计。无论您是在构建自动化商户机器人还是个人理财助手，此技能都为安全、程序化的比特币交互提供了所需的基础设施。

下载入口:https://github.com/openclaw/skills/tree/main/skills/echennells/sparkbtcbot-proxy-deploy

安装与下载

1. ClawHub CLI

从源直接安装技能的最快方式。

2. 手动安装

将技能文件夹复制到以下位置之一

优先级：工作区 > 本地 > 内置

3. 提示词安装

将此提示词复制到 OpenClaw 即可自动安装。

Spark Bitcoin L2 代理部署器 应用场景

• 在不共享私钥的情况下，授予 AI 代理对比特币浅包的受限访问权限
• 为具有严格支出限制的自主代理自动执行闪电网络支付
• 设置仅能创建和坚控发票但不能支出资金的商户机器人
• 将 L402 付费墙支持集成到自动化研究或数据检索工作流中
• 通过中心化的 Redis 日志追踪代理交易历史和财务活动

1. 该技能在 Vercel 上初始化一个无服务器环境，从环境变量中提取配置。
2. 它通过 Spark SDK 和基于 HTTP/2 的 gRPC 建立与 Spark Bitcoin L2 网络连接。
3. 传入请求使用 Bearer 令牌进行身份验证，该令牌针对 Redis 数据库或备用管理员令牌进行验证。
4. 对于付款请求，代理会根据预定义的 MAX_TRANSACTION_SATS 和 DAILY_BUDGET_SATS 限制检查当前支出。
5. 执行经过验证的操作（如转账或发票创建），并将结果记录到 Redis 以进行持久化和审计。
6. 对于 L402 请求，代理会自动处理挑战-响应周期，支付发票并缓存生成的令牌。

Spark Bitcoin L2 代理部署器 配置指南

按照以下步骤使用 Openclaw Skills 部署代理：

1. 克隆仓库：

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

2. 配置 Redis： 通过 Upstash 创建全局数据库以处理状态和日志。

3. 准备环境变量： 生成管理员令牌和您的 BIP39 助记词。

4. 部署到 Vercel：

npx vercel --prod

5. 配置变量： 将 SPARK_MNEMONIC、API_AUTH_TOKEN、UPSTASH_REDIS_REST_URL 和支出限制添加到您的 Vercel 项目设置中，然后重新部署。

Spark Bitcoin L2 代理部署器 数据架构与分类体系

该技能使用以下架构组织其基础设施和状态：

name: sparkbtcbot-proxy-deploy
description: Deploy a serverless Spark Bitcoin L2 proxy on Vercel with spending limits, auth, and Redis logging. Use when user wants to set up a new proxy, configure env vars, deploy to Vercel, or manage the proxy infrastructure.
argument-hint: "[Optional: setup, deploy, rotate-token, or configure]"

Deploy sparkbtcbot-proxy

You are an expert in deploying and managing the sparkbtcbot-proxy — a serverless middleware that wraps the Spark Bitcoin L2 SDK behind authenticated REST endpoints on Vercel.

What This Proxy Does

Gives AI agents scoped wallet access without exposing the mnemonic:

• Role-based token auth (admin for full access, invoice for read + create invoices only)
• Token management via API — create, list, revoke without redeploying
• Per-transaction and daily spending caps
• Activity logging to Redis
• Lazy detection of paid Lightning invoices

What You Need

Ask the user for these upfront:

• Vercel account (free Hobby tier works)
• Upstash account email and API key (from https://console.upstash.com/account/api) — OR existing UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN if they already have a database
• BIP39 mnemonic for the Spark wallet (or generate one in step 3)
• Node.js 20+

Generated during setup (don't ask for these):

• UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN — created by the Upstash management API in step 2
• API_AUTH_TOKEN — generated in step 4

Step-by-Step Deployment

1. Clone and install

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

2. Create Upstash Redis

If the user already has UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN, skip to step 3.

Otherwise, create a database via the Upstash API. The user needs their Upstash email and API key from https://console.upstash.com/account/api:

curl -X POST "https://api.upstash.com/v2/redis/database" r
  -u "UPSTASH_EMAIL:UPSTASH_API_KEY" r
  -H "Content-Type: application/json" r
  -d '{"name": "sparkbtcbot-proxy", "region": "global", "primary_region": "us-east-1"}'

Note: Regional database creation is deprecated. You must use "region": "global" with a "primary_region" field. The Upstash docs may not reflect this yet.

The response includes rest_url and rest_token — save these for step 5.

3. Generate a wallet mnemonic (if needed)

SparkWallet.initialize() returns { mnemonic, wallet } when called without a mnemonic. One-liner:

node -e "import('@buildonspark/spark-sdk').then(({SparkWallet}) => SparkWallet.initialize({mnemonicOrSeed: null, options: {network: 'MAINNET'}}).then(r => { console.log(r.mnemonic); r.wallet.cleanupConnections() }))"

Save the 12-word mnemonic securely — it controls all funds in the wallet. There is no getMnemonic() method; you can only retrieve the mnemonic at initialization time.

Or use any BIP39 mnemonic generator. 12 or 24 words.

4. Generate an API auth token

openssl rand -base64 30

5. Deploy to Vercel

npx vercel --prod

When prompted, accept the defaults. Then set environment variables. All 7 are required:

Important: Do NOT use vercel env add with heredoc/<<< input — it appends newlines that break the Spark SDK. Either use the Vercel dashboard or the REST API:

curl -X POST "https://api.vercel.com/v10/projects//env?teamId=" r
  -H "Authorization: Bearer " r
  -H "Content-Type: application/json" r
  -d '{"type":"encrypted","key":"SPARK_MNEMONIC","value":"your mnemonic here","target":["production","preview","development"]}'

Redeploy after setting env vars:

npx vercel --prod

6. Test

curl -H "Authorization: Bearer " https://.vercel.app/api/balance

Should return {"success":true,"data":{"balance":"0","tokenBalances":{}}}.

7. Create scoped tokens (optional)

Use the admin token to create limited tokens for agents:

curl -X POST -H "Authorization: Bearer " r
  -H "Content-Type: application/json" r
  -d '{"role": "invoice", "label": "my-agent"}' r
  https://.vercel.app/api/tokens

The response includes the full token string — save it, it's only shown once. See the Token Roles section below for details.

API Routes

Token Roles

There are two token roles:

The API_AUTH_TOKEN env var is a hardcoded admin fallback — it always works even if Redis is down or tokens get wiped. Use it to bootstrap: create scoped tokens via the API, then hand those out to agents.

Managing tokens

Create an invoice-only token for a merchant bot:

curl -X POST -H "Authorization: Bearer " r
  -H "Content-Type: application/json" r
  -d '{"role": "invoice", "label": "merchant-bot"}' r
  https:///api/tokens

List all tokens (shows prefixes, labels, roles — not full token strings):

curl -H "Authorization: Bearer " https:///api/tokens

Revoke a token:

curl -X DELETE -H "Authorization: Bearer " r
  -H "Content-Type: application/json" r
  -d '{"token": ""}' r
  https:///api/tokens

Tokens are stored in Redis (hash spark:tokens). They survive redeploys but not Redis flushes.

L402 Paywall Support

The proxy can pay L402 Lightning paywalls automatically. Send a URL, and the proxy will:

1. Fetch the URL
2. If 402 returned, parse the invoice and macaroon
3. Pay the Lightning invoice
4. Retry the request with the L402 Authorization header
5. Return the protected content

Basic usage

curl -X POST -H "Authorization: Bearer " r
  -H "Content-Type: application/json" r
  -d '{"url": "https://lightningfaucet.com/api/l402/joke"}' r
  https:///api/l402

Handling pending payments (important for agents)

Lightning payments via Spark are asynchronous. The proxy polls for up to ~7.5 seconds, but if the preimage isn't available in time, it returns a pending status:

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

Your agent MUST handle this case. The payment has already been sent — if you don't poll for completion, you lose the sats without getting the content.

Retry loop (pseudocode):

response = POST /api/l402 { url: "..." }

if response.data.status == "pending":
    pendingId = response.data.pendingId
    for attempt in 1..10:
        sleep(3 seconds)
        status = GET /api/l402/status?id={pendingId}
        if status.data.status != "pending":
            return status.data  # Success or failure
    # Give up after ~30 seconds
    raise "L402 payment timed out"
else:
    return response.data  # Immediate success

Key points:

• Token caching: Paid L402 tokens are cached per-domain (up to 24 hours). Subsequent requests to the same domain reuse the cached token without paying again. If the token expires, the proxy pays for a new one automatically.
• Pending records expire after 1 hour
• The /api/l402/status endpoint polls Spark for up to 5 seconds per call
• If the payment failed on Spark's side, status will return an error
• Once complete, the pending record is deleted from Redis
• The proxy automatically retries the final fetch up to 3 times (200ms delay) if the response is empty — some servers don't return content immediately after payment

Common Operations

Rotate the admin fallback token

1. Generate a new token: openssl rand -base64 30
2. Update API_AUTH_TOKEN in Vercel env vars
3. Redeploy: npx vercel --prod
4. Update any agents using the old token

Redis-stored tokens are not affected by this — they continue working.

Adjust spending limits

Update MAX_TRANSACTION_SATS and DAILY_BUDGET_SATS in Vercel env vars and redeploy. Budget resets daily at midnight UTC.

Check logs

curl -H "Authorization: Bearer " https:///api/logs?limit=20

Architecture

• Vercel serverless functions — each request spins up, initializes the Spark SDK (~1.5s), handles the request, and shuts down. No always-on process, no billing when idle.
• Upstash Redis — stores daily spend counters, activity logs, pending invoice tracking, and API tokens. Accessed over HTTP REST (no persistent connection needed). Free tier is limited to 1 database.
• Spark SDK — @buildonspark/spark-sdk connects to Spark Signing Operators via gRPC over HTTP/2. Pure JavaScript, no native addons.
• Lazy invoice check — on every request, the middleware checks Redis for pending invoices and compares against recent wallet transfers. Expired invoices are cleaned up, paid ones are logged. Max 5 checks per request, wrapped in try/catch so failures never affect the main request.