From sparkbtcbot-proxy
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.
How this skill is triggered — by the user, by Claude, or both
Slash command
/sparkbtcbot-proxy:deploy [Optional: setup, deploy, rotate-token, or configure][Optional: setup, deploy, rotate-token, or configure]The summary Claude sees in its skill listing — used to decide when to auto-load this skill
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.
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.
Gives AI agents scoped wallet access without exposing the mnemonic:
admin for full access, invoice for read + create invoices only)These rules apply whenever this skill is active. The proxy's SPARK_MNEMONIC controls all funds in the wallet — leaks into chat or shell history are catastrophic.
env, printenv, echo $SPARK_MNEMONIC, or cat .env in the conversation.$VERCEL_TOKEN), not echoed back.Ask the user for these upfront:
vercel teams ls)Generated during setup (don't ask for these):
UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN — provisioned automatically when you add the Vercel Marketplace Redis integration (step 2)API_AUTH_TOKEN — generated in step 4git clone https://github.com/echennells/sparkbtcbot-proxy.git
cd sparkbtcbot-proxy
npm install
Recommended: provision Redis as a Vercel Marketplace integration. Vercel handles provisioning, billing, and auto-populates UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN as encrypted env vars on the project. No separate Upstash account or API key juggling.
This is a UI step the user does in their browser (the marketplace flow does not have a stable headless API yet):
sparkbtcbot-proxy project — env vars are auto-attachedIf the user prefers to manage Upstash directly (separate account, multi-project sharing), tell them to create a database at https://console.upstash.com, copy rest_url and rest_token, and they'll set them manually as env vars in step 5.
SparkWallet.initialize() returns { mnemonic, wallet } when called without a mnemonic. The mnemonic controls all funds and cannot be re-derived later (the SDK has no getMnemonic() getter).
Two options:
Option A — let the user generate via a BIP39 tool they trust (paper wallet, hardware wallet, etc.). Lowest exposure, no shell-history risk. Have them paste the resulting 12 or 24 words into the env-var API call in step 5 directly (heredoc into the curl body), never into a shell variable that gets logged.
Option B — generate via the SDK if the user doesn't have a BIP39 generator handy. Pipe the output through Vercel's env-var API in one step so the mnemonic never sits in shell history:
node -e "import('@buildonspark/spark-sdk').then(async ({SparkWallet}) => {
const r = await SparkWallet.initialize({options:{network:'MAINNET'}});
process.stdout.write(r.mnemonic);
await r.wallet.cleanupConnections();
})" | tee /dev/tty | curl -s -X POST "https://api.vercel.com/v10/projects/<PROJECT_ID>/env?teamId=<TEAM_ID>" \
-H "Authorization: Bearer <VERCEL_TOKEN>" \
-H "Content-Type: application/json" \
--data-binary @- \
-d '{"type":"encrypted","key":"SPARK_MNEMONIC","value":"<placeholder — pipe-fill from stdin in real flow>","target":["production","preview","development"]}'
In practice, the cleanest pattern is: print the mnemonic to the user's terminal once with explicit instructions to save it offline, then immediately POST it to Vercel via API and clear the terminal. The user takes responsibility for never letting it land in .bash_history / .zsh_history.
Important: mnemonic generation can only happen at SparkWallet.initialize() time. There is no recovery API. Lose it = lose the wallet.
openssl rand -base64 30
First, create the project and get its ID:
curl -s -X POST "https://api.vercel.com/v10/projects?teamId=<TEAM_ID>" \
-H "Authorization: Bearer <VERCEL_TOKEN>" \
-H "Content-Type: application/json" \
-d '{"name": "sparkbtcbot-proxy", "framework": "nextjs"}'
The response includes id (the project ID) — save it for the next steps.
Then set environment variables via the API. The two UPSTASH_* variables are auto-populated by the Vercel Marketplace Redis integration from step 2 — set them manually only if the user is bringing their own Upstash account.
| Variable | Description | Example |
|---|---|---|
SPARK_MNEMONIC | 12-word BIP39 mnemonic | fence connect trigger ... |
SPARK_NETWORK | Spark network | MAINNET |
API_AUTH_TOKEN | Admin fallback bearer token | output of step 4 |
UPSTASH_REDIS_REST_URL | Auto-populated by marketplace integration; set only if BYO Upstash | https://xxx.upstash.io |
UPSTASH_REDIS_REST_TOKEN | Auto-populated by marketplace integration; set only if BYO Upstash | from Upstash console |
MAX_TRANSACTION_SATS | Per-transaction spending cap | 10000 |
DAILY_BUDGET_SATS | Daily spending cap (resets midnight UTC) | 100000 |
Important: Do NOT use vercel env add with heredoc/<<< input — it appends newlines that break the Spark SDK. Use the REST API:
curl -X POST "https://api.vercel.com/v10/projects/<PROJECT_ID>/env?teamId=<TEAM_ID>" \
-H "Authorization: Bearer <VERCEL_TOKEN>" \
-H "Content-Type: application/json" \
-d '{"type":"encrypted","key":"SPARK_MNEMONIC","value":"your mnemonic here","target":["production","preview","development"]}'
Repeat for each env var (use "type":"plain" for non-sensitive values like SPARK_NETWORK).
Then deploy using environment variables for reliable non-interactive deployment:
npm install -g vercel
VERCEL_ORG_ID=<TEAM_ID> VERCEL_PROJECT_ID=<PROJECT_ID> \
vercel deploy --prod --yes --token <VERCEL_TOKEN>
Troubleshooting:
ERESOLVE npm errors: Install vercel globally with npm install -g vercel instead of using npxrm -rf .vercel/ and retryVERCEL_ORG_ID and VERCEL_PROJECT_ID env vars as shown abovecurl -H "Authorization: Bearer <your-token>" https://<your-deployment>.vercel.app/api/balance
Should return {"success":true,"data":{"balance":"0","tokenBalances":{}}}.
Use the admin token to create limited tokens for agents:
curl -X POST -H "Authorization: Bearer <admin-token>" \
-H "Content-Type: application/json" \
-d '{"role": "invoice", "label": "my-agent"}' \
https://<your-deployment>.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.
| Method | Route | Description |
|---|---|---|
| GET | /llms.txt | API documentation for bots (no auth required) |
| GET | /api/balance | Wallet balance (sats + tokens) |
| GET | /api/info | Spark address and identity pubkey |
| GET | /api/transactions | Transfer history (?limit=&offset=) |
| GET | /api/deposit-address | Bitcoin L1 deposit address |
| GET | /api/fee-estimate | Lightning send fee estimate (?invoice=) |
| GET | /api/logs | Recent activity logs (?limit=) |
| POST | /api/invoice/create | Create Lightning invoice ({amountSats, memo?, expirySeconds?}) |
| POST | /api/invoice/spark | Create Spark invoice ({amount?, memo?}) |
| POST | /api/pay | Pay Lightning invoice — admin only ({invoice, maxFeeSats}) |
| POST | /api/transfer | Spark transfer — admin only ({receiverSparkAddress, amountSats}) |
| POST | /api/l402 | Pay L402 paywall — admin only ({url, method?, headers?, body?, maxFeeSats?}) |
| GET | /api/l402/status | Check/complete pending L402 (?id=<pendingId>) |
| GET | /api/tokens | List API tokens — admin only |
| POST | /api/tokens | Create a new token — admin only ({role, label}) |
| DELETE | /api/tokens | Revoke a token — admin only ({token}) |
There are two token roles:
| Role | Permissions |
|---|---|
admin | Everything — read, create invoices, pay, transfer, manage tokens |
invoice | Read (balance, info, transactions, logs, fee-estimate, deposit-address) + create invoices. Cannot pay or transfer. |
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.
Create an invoice-only token for a merchant bot:
curl -X POST -H "Authorization: Bearer <admin-token>" \
-H "Content-Type: application/json" \
-d '{"role": "invoice", "label": "merchant-bot"}' \
https://<deployment>/api/tokens
List all tokens (shows prefixes, labels, roles — not full token strings):
curl -H "Authorization: Bearer <admin-token>" https://<deployment>/api/tokens
Revoke a token:
curl -X DELETE -H "Authorization: Bearer <admin-token>" \
-H "Content-Type: application/json" \
-d '{"token": "<full-token-string>"}' \
https://<deployment>/api/tokens
Tokens are stored in Redis (hash spark:tokens). They survive redeploys but not Redis flushes.
The proxy can pay L402 Lightning paywalls automatically. Send a URL, and the proxy will:
curl -X POST -H "Authorization: Bearer <admin-token>" \
-H "Content-Type: application/json" \
-d '{"url": "https://lightningfaucet.com/api/l402/joke"}' \
https://<deployment>/api/l402
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=<pendingId> 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:
/api/l402/status endpoint polls Spark for up to 5 seconds per callopenssl rand -base64 30API_AUTH_TOKEN in Vercel env vars (via dashboard or API)VERCEL_ORG_ID=<TEAM_ID> VERCEL_PROJECT_ID=<PROJECT_ID> \
vercel deploy --prod --yes --token <VERCEL_TOKEN>
Redis-stored tokens are not affected by this — they continue working.
Update MAX_TRANSACTION_SATS and DAILY_BUDGET_SATS in Vercel env vars and redeploy:
VERCEL_ORG_ID=<TEAM_ID> VERCEL_PROJECT_ID=<PROJECT_ID> \
vercel deploy --prod --yes --token <VERCEL_TOKEN>
Budget resets daily at midnight UTC.
curl -H "Authorization: Bearer <token>" https://<deployment>/api/logs?limit=20
@buildonspark/spark-sdk connects to Spark Signing Operators via gRPC over HTTP/2. Pure JavaScript, no native addons.Provides UI/UX resources: 50+ styles, color palettes, font pairings, guidelines, charts for web/mobile across React, Next.js, Vue, Svelte, Tailwind, React Native, Flutter. Aids planning, building, reviewing interfaces.
Fetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.
npx claudepluginhub echennells/sparkbtcbot-proxy --plugin sparkbtcbot-proxy