⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

v0.10.1

sparkbtcbot

echennells@echennells⭐ 5 stars· last commit 5d ago· 0 open issues

Optional override for the spend-ledger file backing SPARK_DAILY_BUDGET_SATS. Defaults to ~/.spark/spend-ledger.json.

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐ 5 on GitHubGitHub ↗

New / niche

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

sparkbtcbot

CI License: MIT Node

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, and set spending limits (sparkbtcbot limits, or just tell the agent in chat); 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. Not an L1 wallet: on-chain, it sees only coins sent to its own Spark deposit addresses (what it can and can't do on L1)
  • 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, to a regular address or a BIP-352 silent payment address (sp1q…)
  • 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-ref

// HOW IT'S BUILT

// FILES

2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • skills/sparkbtcbot/SKILL.md7.9 KBupstream ↗
    ---
    name: sparkbtcbot
    description: Give an AI agent a self-custodial Bitcoin wallet on the Spark L2. Covers wallet init from a BIP39 mnemonic, zero-fee Spark and BTKN/LRC20 token transfers, Lightning invoices (create and pay), Spark native invoices, L402 paywall payment, L1 deposits and cooperative withdrawals, and message signing. Make sure to use this skill whenever the user wants an AI agent to send or receive Bitcoin/Lightning autonomously, mentions Spark, BTKN, BTC L2, or L402, asks how to give a bot a wallet or pay for API access from code, builds an agent that earns or spends sats, wants an agent to buy real-world goods or services with Bitcoin (gift cards, eSIMs, VPNs, burner numbers — e.g. via Bitrefill, nadanada, or Cryptorefills), sets up a non-custodial wallet for an LLM, needs to get paid or settle a debt over Bitcoin/Lightning ("friend owes me $100, he said use sparkbtcbot", "make an invoice for €50"), has sats and asks how to spend, cash out, or "use this" (gift card with Lightning), or describes any agent that needs to move money on Bitcoin — even if they don't say "Spark" specifically.
    argument-hint: "[Optional: specify what to set up - wallet, payments, tokens, lightning, l402, or full]"
    requires:
      env:
        - name: SPARK_PASSPHRASE
          description: Passphrase (minimum 12 characters) that decrypts the BIP39 mnemonic from the encrypted-seed file (~/.spark/seed.enc by default). Useless without the seed file. Run `npm run setup` once to create the encrypted seed.
          sensitive: true
        - name: SPARK_NETWORK
          description: Network to connect to (MAINNET or REGTEST)
          default: MAINNET
        - name: SPARK_SEED_PATH
          description: Optional override for the encrypted-seed file location. Defaults to ~/.spark/seed.enc.
        - name: SPARK_LEAF_VAULT
          description: Set to "off" to disable the automatic recovery-bundle backup (the "leaf-vault" consumed by Blink's unilateral-exit tool). On by default.
        - name: SPARK_PRIVACY
          description: Set to "off" to leave balance and transfer history publicly readable by address (Spark's default). On by default — setup and every boot enable per-wallet privacy.
        - name: SPARK_DAILY_BUDGET_SATS
          description: Opt-in rolling 24-hour cumulative spend budget in sats, enforced across Spark transfers, Lightning pays, Spark-invoice fulfillment, and L1 withdrawals. The one guard that stops a LOOP of individually-valid sends — strongly recommended for any autonomous agent. Unset = no budget.
        - name: SPARK_SPEND_LEDGER_PATH
          description: Optional override for the spend-ledger file backing SPARK_DAILY_BUDGET_SATS. Defaults to ~/.spark/spend-ledger.json.
    model-invocation: autonomous
    model-invocation-reason: Agents autonomously send and receive Bitcoin — paying invoices and answering incoming transfers without per-transaction human approval is the point. This path is full custody once decrypted, with no server-enforced spending caps; bound the blast radius with a dedicated small-float wallet, SPARK_DAILY_BUDGET_SATS, and the recipient allowlist.
    ---
    
    # Spark Bitcoin L2 for AI Agents
    
    You are an expert in setting up Spark Bitcoin L2 wallet capabilities for AI agents using `@buildonspark/spark-sdk` — and in spending those sats safely at Bitcoin-accepting merchants (see the merchant references in the navigator below).
    
    > **Read this first — what you're handing an AI agent.** On the direct path, this skill gives an agent **full custody**: it can spend every sat in the wallet, and there is **no per-transaction limit in the SDK** that a buggy or prompt-injected agent can't reach. That's manageable, not scary — but only if you scope it. **Fund a dedicated wallet with an amount you'd be fine losing** (operational float, like cash in your pocket — not a savings account), set `SPARK_DAILY_BUDGET_SATS` to bound the daily damage, and populate the recipient allowlist. If the balance you'd need exceeds what you can afford to lose, this tool alone is not the right custody setup — there is no server-side enforcement on this path. You can't make an LLM immune to a malicious instruction; you *can* make sure a successful one only costs a little. The Custody Model section below and `references/security.md` explain the trade-offs in full.
    
    Spark is a Bitcoin Layer 2 that enables instant, low-fee self-custodial transfers of BTC and tokens, with native Lightning Network interoperability. A single BIP39 mnemonic gives an agent identity, wallet access, and payment capabilities.
    
    ## Custody Model
    
    **This skill gives the agent full custody of the wallet.** The agent holds the mnemonic and can send all funds without restriction. Use the direct path **only** for:
    - **Development and testing** — REGTEST, no real funds.
    - **A dedicated wallet holding only what you can afford to lose** — the operational float the agent actually needs, swept regularly, never a treasury.
    
    Note what's deliberately *not* on that list: "an agent I trust." Trust isn't the safeguard here — an agent can be steered by a malicious instruction in a webpage, a task, or a merchant response no matter how much you trust *it*, and once that happens it has the same full spend authority you do. The in-process guardrails below (allowlist, `SPARK_DAILY_BUDGET_SATS`, amount caps) bound the damage from that; they don't prevent it, and a fully compromised process can bypass them. So size the balance to the blast radius you can absorb.
    
    **There is no server-enforced variant of this skill** — no scoped tokens, no server-side caps, no revocation short of sweeping to a new wallet. The in-process guardrails below are the strongest controls available here, and because they live in the agent's own process, a fully compromised process can bypass them. That makes the sizing rule above the real control: the funded balance is the only cap that survives compromise. Hold only what you can afford to lose, and sweep regularly.
    
    ## Optional agent-side guardrails (direct skill)
    
    Even on the direct path, the wrapper exposes three opt-in safety knobs. They are *not* hard-enforced controls (anything with FS access can defeat them) — they exist to keep the agent from surprising the operator, and to make the "ask before spending" pattern natural.
    
    - **`dryRun: true` on send operations — SparkAgent wrapper ONLY.** `agent.transfer({ to, amount, dryRun: true })` returns `{ from, to, amount, estimatedFee, network }` without signing or broadcasting. Use it when stakes are non-trivial — show the preview, confirm with the operator, then re-call without `dryRun`. The same flag works on `agent.transferTokens`, `agent.withdraw`, and `agent.payLightningInvoice`. **The allowlist (below) is enforced in dry-run mode too**, so dry-runs can't be used to silently confirm a send to a disallowed address.
      **⚠️ The raw SDK has NO `dryRun`.** `wallet.transfer({ ..., dryRun: true })` is NOT a preview: JavaScript silently drops the unknown key and the call **signs and sends**. The same applies to every raw `wallet.*` money-moving call — and the raw path also bypasses the recipient allowlist and the `lib/fee-guards.js` ceilings, which live in the wrapper. If you are not using `SparkAgent`, there is no dry-run; say so instead of faking one.
    
    - **Address allowlist at `~/.spark/recipients.allow`.** One Spark / L1 address per line, `#` comments OK. If the file is missing or empty → no enforcement. If it contains at least one entry → every Spark transfer, token transfer, Spark-invoice fulfillment (the receiver is decoded from the invoice itself), and L1 withdrawal must target an address in the file. Bypass is "edit the file" — by design. (Lightning/L402 are not gated by the allowlist — see the caveat below.)
    
    - **Cumulative spend budget via `SPARK_DAILY_BUDGET_SATS`.** Every other guard is per-call, so none of them stops a *loop* of individually-valid sends. Set this env var and the wrapper enforces a rolling 24-hour sats budget across Spark transfers, Lightning pays, Spark-invoice fulfillment, and 
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/echennells-sparkbtcbot-skills-sparkbtcbot.md

// REPO STATS

5 stars
0 open issues
Last commit: 5d ago