Use a Spark Bitcoin L2 wallet proxy for AI agents via HTTP API. Check balances, send payments, create invoices, pay L402 paywalls — all without holding the mnemonic. Use when user mentions "Spark proxy," "wallet API," "L402," "proxy payment," "bearer token auth," or wants secured Bitcoin capabilities for an agent.
Use a Spark Bitcoin L2 wallet proxy for AI agents via HTTP API. Check balances, send payments, create invoices, pay L402 paywalls — all without holding the mnemonic. Use when user mentions "Spark proxy," "wallet API," "L402," "proxy payment," "bearer token auth," or wants secured Bitcoin capabilities for an agent.
{"env":[{"name":"PROXY_URL","description":"HTTPS URL of your deployed sparkbtcbot-proxy instance (e.g., https://your-app.vercel.app)","sensitive":false},{"name":"PROXY_TOKEN","description":"Bearer token for proxy authentication. Create via POST /api/tokens with an admin token. Use least-privilege roles — prefer 'read-only', 'invoice', or 'pay-only' over 'admin' for agents.","sensitive":true}]}
model-invocation
autonomous
model-invocation-reason
This skill enables agents to call a wallet proxy API. Autonomous invocation is intentional for payment workflows, but the proxy enforces spending limits and role-based access. Always use least-privilege tokens and set per-tx/daily caps on the proxy side.
Spark Bitcoin L2 Proxy for AI Agents
You are an expert in using the sparkbtcbot-proxy — a serverless HTTP API that gives AI agents scoped access to a Spark Bitcoin L2 wallet without exposing the private key.
Why Use the Proxy Instead of Direct SDK
Concern
Direct SDK (sparkbtcbot-skill)
Proxy (this skill)
Mnemonic location
Agent holds it
Server holds it
Spending limits
None (agent decides)
Per-tx and daily caps
Access revocation
Move funds to new wallet
Revoke bearer token
Role-based access
No
Yes (admin, invoice, pay-only, read-only)
Setup complexity
npm install + mnemonic
HTTP calls + bearer token
Use the proxy when:
You don't trust the agent with full wallet control
You need spending limits or audit logs
You want to revoke access without moving funds
Multiple agents share one wallet with different permissions
Use direct SDK when:
Testing or development
Agent needs offline signing
You're building the proxy itself
Before You Start
Deploy your own proxy — see sparkbtcbot-proxy for setup instructions. The proxy runs on Vercel (free tier works) with Upstash Redis.
Use HTTPS only — never connect to a proxy over plain HTTP. All Vercel deployments use HTTPS by default.
Create least-privilege tokens — don't give agents admin tokens. Use the most restrictive role that works:
read-only for monitoring/dashboard agents
invoice for agents that receive payments but don't spend
pay-only for agents that pay L402 paywalls but don't create invoices
admin only for your own management scripts
Set spending limits — configure maxTxSats and dailyBudgetSats when creating tokens. The proxy enforces these server-side.
Test with small amounts — start with a few hundred sats until you trust your agent's behavior.
Have a revocation plan — know how to revoke tokens via DELETE /api/tokens if an agent is compromised.
Token Roles
Role
Permissions
admin
Full access: read, create invoices, pay, transfer, manage tokens
invoice
Read + create invoices. Cannot pay or transfer.
pay-only
Read + pay invoices and L402. Cannot create invoices or transfer.
read-only
Read only (balance, info, transactions, logs). Cannot pay or create invoices.
Base URL
The proxy runs on Vercel. Your base URL will look like:
Lightning payments are asynchronous. If the preimage isn't available within ~7.5 seconds, the proxy returns a pending status:
{"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}}
You MUST handle this case. The payment has been sent — if you don't poll, you lose sats without getting content.
