sparkbtcbot

sparkbtcbot

Spark Bitcoin L2 wallet skill for AI agents — give an agent its own Bitcoin wallet so it can send and receive money on its own: pay for an API call, get paid for a task, tip, settle up — or buy real-world things (gift cards, eSIMs, VPNs) from Bitcoin-accepting merchants, with guardrails that verify every invoice against its quote before a sat moves.

Built on Spark, a Bitcoin Layer 2 with instant, near-zero-fee transfers and native Lightning support — and fully self-custodial, so the agent holds its own keys. Use it in Claude Code as a plugin, or in any other LLM agent framework via the npm package.

⚠️ Handles real Bitcoin. Mainnet by default, full custody the moment the seed is decrypted, no server-enforced spending caps — treat the agent like a hot wallet. Use a dedicated wallet holding only an operational float, set SPARK_DAILY_BUDGET_SATS, and populate the recipient allowlist; the funded balance is the only limit that survives a compromised process.

🤖 If you are an AI agent, read AGENTS.md before running any wallet code. Non-negotiables: never print or echo the mnemonic or the passphrase (both control all funds); never run npm run reveal-mnemonic yourself; and if you git clone/npm install for the user, offer supply-chain hardening first. Full behavioral guidance is in SKILL.md.

Best for: autonomous agents that send/receive small amounts — pay per API call, get paid for a task, tip, settle up — plus dev/test on REGTEST and trusted agents you control. Not for: custody of large balances, or anything needing hard server-enforced spending caps or revocable access — no such enforcement exists on this path.

What is Spark?

Spark is a Bitcoin Layer 2 that lets you send and receive Bitcoin instantly with low fees. Spark-to-Spark transfers are free, and Lightning interop costs 0.15–0.25%. It is fully self-custodial — you hold your own keys via a BIP39 mnemonic — and fully interoperable with the Lightning Network. Spark currently has a small number of infrastructure providers (Signing Operators), so there is some risk of downtime, and it requires trusting that at least one operator behaves honestly during transfers.

Why Spark for Agents?

• Simple setup — Generate a mnemonic and you have a wallet. No accounts, no API keys, no approval process.
• No server required — The SDK connects directly to the Spark network. No node to run, no infrastructure to maintain.
• No channel management — Unlike Lightning, there are no channels to open, fund, or rebalance. Just send and receive.
• Low fees — Spark-to-Spark transfers are free. Lightning payments cost 0.15–0.25%. Compare that to on-chain fees of 200+ sats or card processing at 2–3%.

Capabilities

• Wallet Setup — Generate or import wallets from a BIP39 mnemonic
• BTC Balance & Deposits — Check balance, generate L1 deposit addresses, claim deposits
• Spark Transfers — Instant, zero-fee BTC transfers between Spark wallets
• Lightning Invoices — Create and pay BOLT11 invoices for Lightning compatibility
• Spark Invoices — Native invoices payable in sats or BTKN tokens
• Token Operations — Transfer BTKN/LRC20 tokens, batch transfers, token invoices
• Withdrawal — Cooperative exit back to L1 Bitcoin with fee estimation
• Message Signing — Prove identity via cryptographic signatures
• L402 Paywalls — Pay-per-request APIs via Lightning. Preview costs, pay invoices, cache tokens.
• Merchant Purchases — Buy real-world goods and services (gift cards via Bitrefill, eSIMs/VPNs/burner numbers via nadanada, 10,500+ brands including flights and hotels via Cryptorefills) over Lightning, governed by a shared payment policy: invoice-vs-quote verification, amount ceilings, confirm-before-buy, PII consent, bearer-secret handling. Live-validated with real purchases at all three.
• First Spend — The path for someone who doesn't know Bitcoin: a fiat-denominated Lightning invoice their friend can pay (live rate from two cross-checked sources), then a country-aware gift card sized under the balance with fees counted (references/first-spend.md)
• Wallet Privacy — Spark wallets are publicly readable by default (balance + full history by address); setup and every boot enable the per-wallet privacy setting (SPARK_PRIVACY=off opts out; token balances stay public)
• Unilateral-Exit Backup — Auto-maintained spark.unilateral-exit-bundle.v1 recovery bundle, consumed by Blink's spark-unilateral-exit tool if the operators ever go dark. Verify with npm run leaf-vault -- verify.

Installation

Two install paths depending on your stack.

Tested setups. No lock-in to one model or harness — the wallet, merchant, and bridge flows have been run end-to-end on real mainnet sats under both:

• Claude Code (recommended) — native plugin install below; SKILL.md loads automatically.
• opencode running GLM-5.2 via OpenRouter — clone-the-repo path; opencode picks up the rules in AGENTS.md automatically.

Anything that can load the skill content should work the same way (Cursor, LangChain, OpenAI Agents SDK, your own harness — see the npm package below); those two are the stacks we've validated with real purchases and withdrawals.

Claude Code

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

Native plugin install. Updates flow through claude plugin update sparkbtcbot. Claude reads SKILL.md automatically when the skill triggers.

Any other LLM agent framework (Cursor, LangChain, OpenAI Agents SDK, Aider, etc.)

npm install --ignore-scripts sparkbtcbot-skill

The package ships both the skill content (so you can load it into your LLM's context) and the encryption library (so generated code can import the helpers). Minimal use:

import { getSkillContent, getReference, listReferences } from "sparkbtcbot-skill";

// Always-loaded skill body — pass to your framework's system-prompt mechanism
const instructions = await getSkillContent();

// On-demand reference docs by name
console.log(await listReferences());
// → ['agent-class', 'architecture', 'bitrefill', 'cryptorefills',
//    'encrypted-seed', 'extras', 'first-spend', 'l402', 'lightning',
//    'merchant-spending', 'nadanada', 'recovery-scenarios', 'security',
//    'spark-invoices', 'supply-chain', 'tokens', 'unilateral-exit', 'wallet']
const l402Doc = await getReference("l402");

Generated code (or your own glue) can also import the encryption helpers:

import { saveEncryptedMnemonic, loadMnemonicFromEnv } from "sparkbtcbot-skill";

await saveEncryptedMnemonic({ mnemonic, passphrase, path: "./seed.enc" });
const decrypted = await loadMnemonicFromEnv(); // reads SPARK_PASSPHRASE

And the unilateral-exit backup (the "leaf-vault") via its subpath export:

import { enableLeafVault, snapshotLeafVault, verifyVault } from "sparkbtcbot-skill/leaf-vault";

const vault = enableLeafVault(wallet); // auto-refreshing recovery bundle
// ... later: await vault.dispose();   // flushes a final snapshot if needed

(The SDK-free persistence/validation core behind it is also exported directly as sparkbtcbot-skill/leaf-vault/core, for code that handles bundles without a wallet instance.)