Wallet setup and seed security.

Prerequisites

• Node 20 or newer. The package declares engines.node >= 20.
• A passphrase of at least 12 characters, which you will need on every boot. Treat it like a production secret — deployment secret manager, or .env that is in .gitignore.
• Somewhere offline to write 12 words down. Paper, a hardware backup, or a password manager. Have it ready before you run setup, not after.

Claude Code

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

Grok Bot

Prefer a chat window to a terminal? The same skill is published as a shared Bot for Grok Bot, xAI's desktop agent. Open the share link, preview what the Bot ships with, and choose Add to Grok Bot — it becomes a copy in your own account.

Any other agent: the npm package

Cursor, LangChain, the OpenAI Agents SDK, or your own harness — install the package and load the skill body with getSkillContent(). opencode works differently: it's a CLI that discovers skills from directories rather than calling a function, so it needs the one-line registration below.

npm install --ignore-scripts sparkbtcbot-skill

# from your project directory, after installing
$ ln -s "$(pwd)/node_modules/sparkbtcbot-skill/skills/sparkbtcbot" \
       ~/.claude/skills/sparkbtcbot

Clone the repo

No plugin, no marketplace — clone it and let the agent read the skill straight from the repo.

$ git clone https://github.com/echennells/sparkbtcbot
$ cd sparkbtcbot && npm ci --ignore-scripts   # lockfile-exact; no install scripts
# then: "read this repo and set me up a Spark wallet"

Your agent can run this for you — it is the one setup step that is safe to delegate, because the words are never printed. The commands below are the same thing run by hand.

However the skill text reached you — plugin, clone or npm — the runtime is always the sparkbtcbot-skill package installed in your own project, so start with npm install --ignore-scripts sparkbtcbot-skill there, so your application code loads a version your lockfile pins. --ignore-scripts is worth keeping: one transitive dependency (protobufjs) runs code at install time, and nothing here needs it. The one-off setup and backup commands below are then invoked with npm exec --no -- from that same project directory — including the fresh terminal you open for the seed backup, where you cd there first.

# The SDK generates a new 12-word mnemonic and the script encrypts it.
# The words are never printed and never hit disk in plaintext.
$ SPARK_NETWORK=MAINNET npm exec --no -- sparkbtcbot setup

# Bringing a mnemonic from paper, a hardware wallet, or another machine.
# It prompts on stderr — nothing lands in shell history.
$ npm exec --no -- sparkbtcbot setup --import

# One-time path off a pre-existing plaintext SPARK_MNEMONIC in .env.
# Leave that line in place, add SPARK_PASSPHRASE, then run setup.
$ npm exec --no -- sparkbtcbot setup

# Afterwards, delete the SPARK_MNEMONIC line from .env.

The passphrase

Setup reads SPARK_PASSPHRASE from the environment if it is set, and otherwise prompts for it on stderr with a confirmation. It must be at least 12 characters. Whichever way you supply it at setup time, it has to remain available to the runtime afterwards — the wallet decrypts the seed on every boot. If you set it inline for the setup invocation only, put it in .env now.

A fresh wallet's twelve words exist in exactly one place: inside seed.enc, encrypted. Setup never prints them and never writes them to disk in plaintext. To read them, you decrypt them deliberately — in your own terminal, not through your agent:

$ npm exec --no -- sparkbtcbot reveal-mnemonic

Why the agent must not run it

The command refuses to run unless both stdin and stdout are real TTYs. An agent shelling out over a normal Bash tool has piped stdio, so it is refused — as is CI, and anything on the end of a pipe. The interactive y/N confirmation is a second gate that piped stdin cannot auto-answer.

• scrypt for key derivation — N=2^17, r=8, p=1. Memory-hard and OWASP-blessed for password hashing. Roughly 250 ms on a modern CPU; slow on purpose, so brute-forcing your passphrase is expensive.
• AES-256-GCM for encryption — 256-bit key, 96-bit IV, 128-bit auth tag. Authenticated, so a wrong passphrase or tampered ciphertext is detected rather than silently producing garbage.
• Node's built-in node:crypto — zero additional dependencies in the path that touches your seed.

1 byte  version      0x01 = v1 · 0x02 = v2 (seed-bound budget)
1 byte  kdf id       0x01 = scrypt
1 byte  cipher id    0x01 = aes-256-gcm
1 byte  reserved     0x00
16 bytessalt
12 bytesiv           gcm nonce
16 bytesauth tag
N bytes ciphertext

At runtime

Your application reads SPARK_PASSPHRASE from the environment, decrypts the file once at boot, and holds the wallet. The mnemonic falls out of scope; only the wallet object is retained.

import "dotenv/config";
import { SparkWallet } from "@buildonspark/spark-sdk";
import { loadMnemonicFromEnv } from "sparkbtcbot-skill";

const mnemonic = await loadMnemonicFromEnv(); // reads SPARK_PASSPHRASE
const { wallet } = await SparkWallet.initialize({
  mnemonicOrSeed: mnemonic,
  options: { network: process.env.SPARK_NETWORK || "MAINNET" },
});
// `mnemonic` falls out of scope; only `wallet` is retained

What encryption at rest does not do

• It doesn't stop memory dumps. After loadMnemonicFromEnv() returns, the mnemonic is in memory. Attacking that needs shell on the host under the same UID as the agent.
• It doesn't stop a compromised host while the process is running — same reason.
• It doesn't give you scoped or revocable access. Encryption at rest is all-or-nothing: whoever can decrypt has full custody, and you cannot revoke that without sweeping to a new wallet.

The mnemonic doesn't cover the operators-gone case

Restoring from the mnemonic recovers cooperative access — the normal case, where Spark's Signing Operators are online. Unilateral exit additionally needs the wallet's local leaf material, the pre-signed transactions operators hand out at claim and transfer time, which is not derivable from the mnemonic.

That is what the auto-maintained recovery bundle (the "leaf-vault") is for. It refreshes on every balance change, and its integrity gate refuses to write a bundle unless every leaf reconstructs a complete exit chain offline — so a written bundle is an exitable one. Blink's spark-unilateral-exit tool consumes it. Check yours:

$ npm exec --no -- sparkbtcbot leaf-vault verify

Because the fee is flat and is deducted from the amount, small withdrawals are fee-dominated: discourage any L1 exit under 25,000 sats and batch small balances into one. Always quote first and show the user the net they will receive. The cooperative exit is performed by the Spark operators, who can delay but not take funds; the operator-less path is the unilateral exit.

Protect the two secrets

• Back up the seed phrase offline. Paper or a hardware backup. The encrypted seed file is not a substitute.
• Never expose either secret in code, logs, git history, or error messages.
• Treat SPARK_PASSPHRASE like a production secret. Out of source, out of build images, out of CI logs. A secret manager is fine; a gitignored .env is fine; a screenshot in a Slack thread is not.
• Leave seed.enc at mode 0600, and don't bundle it into container images that ship the passphrase alongside it.

Don't accumulate a balance

• Keep only the minimum operational float the agent needs on Spark.
• Sweep earnings out to cold storage or a wallet you control directly, using wallet.transfer() or wallet.withdraw(). There is no automated sweeper in this skill — do it as part of your ops rhythm, or build the listener yourself (transfer:claimed event, balance check, transfer).
• Size the float as a loss you could absorb without changing your day.

Per-agent hygiene

• Separate mnemonics per agent — never share one across agents. Each runs its own setup with its own seed file and passphrase.
• Separate accountNumber values if you want multiple wallets from a single mnemonic, or to split funding tiers.
• Monitor transfers with event listeners for unexpected outgoing activity.
• Call cleanup() when the wallet is no longer needed.
• REGTEST for development, MAINNET only for production.

Seal the budget into the seed

Requires sparkbtcbot-skill 0.6.1 or newer for this command form. The capability landed in 0.5.0, under the per-command binaries that 0.6.0 retired.

SPARK_DAILY_BUDGET_SATS has a structural weakness: it is enforced from files the agent can write. Deleting or truncating ~/.spark/spend-ledger.json, or dropping the line from .env, silently restores the full balance — a cleanup command, a prompt injection or a machine migration all fail open. Since 0.5.0 you can bind the cap into the encrypted seed instead:

$ npm exec --no -- sparkbtcbot set-policy

• A bound budget beats the env var absolutely. Raising SPARK_DAILY_BUDGET_SATS cannot loosen it.
• Tampering fails closed. A missing, unsigned or edited ledger stops spending and tells you to run sparkbtcbot reset-ledger — the passphrase-gated legitimate reset, which is what finally makes a real reset distinguishable from an attack. Previously rm was both.
• The agent can't remove the cap without removing the money. Reading the policy needs the passphrase, tampering fails the GCM tag, and deleting the payload deletes the wallet.
• It is opt-in and backward compatible. v1 seeds and env-var budgets behave exactly as before.

The recipient allowlist

An optional file that pins outbound sends to addresses you named in advance. There is no env var and no flag — it turns on by existing. Create ~/.spark/recipients.allow with at least one address and every gated send checks against it; leave the file absent and nothing is enforced.

# One address per line. Spark and L1 addresses share the file.
sp1q...your-cold-wallet          # sweep target
bc1q...your-hardware-wallet     # L1 withdrawals

# bc1q...old-address            <- commented out, so not permitted

• An empty file means not enforced, and so does a file where every line is commented out. Zero entries reads as "still setting this up" rather than "permit nothing" — so a file you meant as a lockdown but left blank silently permits everything. Verify with a send to an address you did not list.
• Edits apply immediately. The file is re-read on every check rather than cached at boot, so adding a recipient does not need an agent restart.
• Keep it out of the agent's writable working tree. The gate is enforced in the same process as the agent, so bypassing it is just editing the file — it stops the agent from surprising you, not an attacker who already has the host.

If any of these describe your setup, this skill alone is not sufficient custody infrastructure. Keep the balance here to an operational float and hold the rest elsewhere:

• Non-trivial balances — rule of thumb, more than you'd lose without changing your day.
• Multiple agents needing access to the same funds.
• A need for revocable or role-scoped access instead of all-or-nothing custody.
• A need for spending caps that survive a compromised agent process.
• A need for an audit trail of every wallet operation.

Spark itself carries its own assumptions worth knowing: it has a small number of infrastructure providers (Signing Operators), so there is some downtime risk, and transfers require trusting that at least one operator behaves honestly.

Found a security issue? Please don't open a public GitHub issue. Email eric@yvrbtclabs.dev with a description and impact, steps to reproduce, the affected version (npm view sparkbtcbot-skill version or a commit SHA), and your severity assessment if you have one. Expect an acknowledgement within 7 days, and coordinated disclosure timing before any public write-up.