agent-wallet

Self-custodial Bitcoin Lightning wallet for AI agents. Use when the agent needs to send or receive bitcoin payments, check its balance, generate invoices, or...

Security Scan

The skill appears to do what it claims (a self-custodial Lightning wallet) but has several practical risks and small incoherences — in particular: it persists a BIP39 mnemonic to disk, encourages running code via npx (dynamic downloads/unpinned), and contains contradictory guidance about revealing the mnemonic — all of which could let an agent or other process exfiltrate private keys if you install it without careful review and isolation.

Purpose & Capability

The declared requirements (node, npx) and the runtime instructions (npx @moneydevkit/agent-wallet) match the stated purpose of running an npm-based wallet CLI/daemon. No unrelated credentials or binaries are requested.

Instruction Scope

The SKILL.md instructs the agent to run npx commands that generate and store a BIP39 mnemonic at ~/.mdk-wallet/config.json and to start a localhost daemon. It also documents an `init --show` mode that appears to return the mnemonic (the file also says the mnemonic is 'redacted' in one place and shown in another) — this ambiguity increases the risk that the agent or other actors might print or transmit the seed. The instructions give the agent the ability to create, persist, and display the private key material and to make outbound network connections; those steps are within a wallet's expected scope but are high-risk operations for secrets.

Install Mechanism

There is no bundled install; the skill relies on npx to run an npm package on-demand. Running code via npx pulls packages from the public registry at runtime and can execute arbitrary code. The SKILL.md recommends pinning a version, but the quick-start commands use unpinned npx invocations by default, which increases supply-chain risk if the npm package or its dependencies were compromised.

Credentials

The skill does not request environment variables or external credentials, which is proportionate. However it creates persistent local secrets (BIP39 mnemonic in ~/.mdk-wallet/config.json) and runs a local HTTP daemon; those files are effectively credentials controlling funds. The skill's own instructions can cause the mnemonic to be shown on stdout, which is a sensitive capability that should be carefully controlled.

Persistence & Privilege

The skill persists sensitive wallet state and a seed phrase to ~/.mdk-wallet/ and runs a background daemon on localhost:3456. This persistence is expected for a self-custodial wallet but it is high-privilege (the mnemonic controls real funds). The skill does not request always: true, nor does it modify other skills, but its persistent secret storage combined with autonomous invocation capability could increase blast radius if misused.

What to consider before installing

Before installing or invoking this skill: (1) Treat the mnemonic as a high-value secret — back it up securely and restrict permissions on ~/.mdk-wallet/. (2) Prefer pinned package invocations (e.g. npx @moneydevkit/agent-wallet@<version>) and review the npm package and GitHub source yourself to ensure there is no unexpected network exfiltration. (3) Be mindful that `init --show` may reveal the seed on stdout; avoid running it in contexts where an agent or other process can forward command output. (4) Run the wallet in an isolated environment (dedicated VM/container) if you plan to hold real funds. (5) If you do not fully trust the package or the agent's autonomy, do not enable automatic or unattended use of wallet commands — require explicit human approval before any command that exports the mnemonic, creates invoices, or sends payments. (6) If you need stronger guarantees, consider hardware-backed wallets or well-audited implementations rather than running unpinned npm packages fetched at runtime.

Self-custodial Lightning wallet for AI agents, built by MoneyDevKit. One command to init. All output is JSON.

Source: @moneydevkit/agent-wallet on npm · GitHub

Security & Transparency

This skill runs @moneydevkit/agent-wallet — an npm package published by MoneyDevKit. What it does:

• Generates and stores a BIP39 mnemonic at ~/.mdk-wallet/config.json — this IS your private key. Treat it like a password.
• Runs a local daemon on localhost:3456 — HTTP server for wallet operations. Binds to localhost only (not externally accessible).
• Connects outbound to MDK's Lightning infrastructure.
• Persists payment history to ~/.mdk-wallet/.

No data is sent to external servers beyond standard Lightning protocol operations. You can verify this by inspecting the source code or the published npm tarball.

Recommended: Pin a version (npx @moneydevkit/agent-wallet@0.11.0) in production.

Quick Start

# Initialize wallet (generates mnemonic)
npx @moneydevkit/agent-wallet init

# Get balance
npx @moneydevkit/agent-wallet balance

# Create invoice
npx @moneydevkit/agent-wallet receive 1000

# Pay someone
npx @moneydevkit/agent-wallet send [e-mail] 500

How It Works

The CLI automatically starts a daemon on first command. The daemon:

• Runs a local HTTP server on localhost:3456
• Connects to MDK's Lightning infrastructure
• Polls for incoming payments every 30 seconds
• Persists payment history to ~/.mdk-wallet/

No webhook endpoint needed — the daemon handles everything locally.

Setup

First-time initialization

npx @moneydevkit/agent-wallet init

This command:

1. Generates a BIP39 mnemonic — 12-word seed phrase that IS your wallet
2. Creates config at ~/.mdk-wallet/config.json
3. Derives a walletId — deterministic 8-char hex ID from your mnemonic
4. Starts the daemon — local Lightning node on port 3456

The wallet is ready immediately. No API keys, no signup, no accounts. The agent holds its own keys.

View existing config

npx @moneydevkit/agent-wallet init --show

Returns { "mnemonic": "...", "network": "mainnet", "walletId": "..." }.

Note: init will refuse to overwrite an existing wallet. To reinitialize:

npx @moneydevkit/agent-wallet stop
rm -rf ~/.mdk-wallet  # WARNING: backup mnemonic first!
npx @moneydevkit/agent-wallet init

Commands

All commands return JSON on stdout. Exit 0 on success, 1 on error.

Command	Description
init	Generate mnemonic, create config
init --show	Show config (mnemonic redacted)
start	Start the daemon
balance	Get balance in sats
receive <amount>	Generate invoice
receive	Generate variable-amount invoice
receive <amount> --description "..."	Invoice with custom description
receive-bolt12	Generate a BOLT12 offer (variable amount, reusable)
send <destination> [amount]	Pay bolt11, bolt12, lnurl, or lightning address
payments	List payment history
status	Check if daemon is running
stop	Stop the daemon
restart	Restart the daemon

Balance

npx @moneydevkit/agent-wallet balance

→ { "balance_sats": 3825 }

Receive (generate invoice)

# Fixed amount
npx @moneydevkit/agent-wallet receive 1000

# Variable amount (payer chooses)
npx @moneydevkit/agent-wallet receive

# With description
npx @moneydevkit/agent-wallet receive 1000 --description "payment for service"

→ { "invoice": "lnbc...", "payment_hash": "...", "expires_at": "..." }

Receive BOLT12 Offer

npx @moneydevkit/agent-wallet receive-bolt12

→ { "offer": "lno1..." }

BOLT12 offers are reusable and don't expire — share one offer and receive unlimited payments to it. Unlike BOLT11 invoices, the payer chooses the amount.

Send

npx @moneydevkit/agent-wallet send <destination> [amount_sats]

Destination auto-detection:

• bolt11 invoice: lnbc10n1... (amount encoded, no arg needed)
• bolt12 offer: lno1...
• lightning address: [e-mail]
• LNURL: lnurl1...

For lightning addresses and LNURL, amount is required:

npx @moneydevkit/agent-wallet send [e-mail] 500

Payment History

npx @moneydevkit/agent-wallet payments

→ { "payments": [{ "paymentHash": "...", "amountSats": 1000, "direction": "inbound"|"outbound", "timestamp": ..., "destination": "..." }] }

Upgrading

# Stop the running daemon
npx @moneydevkit/agent-wallet stop

# Run with @latest to pull the newest version
npx @moneydevkit/agent-wallet@latest start

Your wallet config and payment history in ~/.mdk-wallet/ are preserved across upgrades.

Usage Notes

• Denomination: use ₿ prefix with sats (e.g. ₿1,000 not "1,000 sats")
• Self-custodial: the mnemonic IS the wallet. Back it up. Lose it, lose funds.
• Daemon: runs a local Lightning node on :3456. Auto-starts, persists to disk.
• Agent-to-agent payments: any agent with this wallet can pay any other agent's invoice or lightning address.

What's Next?

Want to accept payments from customers? Use the moneydevkit skill to add checkouts to any website. Agent-wallet handles agent-to-agent payments; moneydevkit handles customer-to-agent payments. Together they give your agent full payment superpowers.