Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.moneydevkit.com/llms.txt

Use this file to discover all available pages before exploring further.

A self-custodial Lightning wallet designed for AI agents. Run it as a CLI — every command outputs JSON to stdout for easy parsing. No API keys, no accounts, no webhooks.
The agent wallet runs a local daemon that leverages moneydevkit’s lightning infrastructure. No node management required.

​
Quick start

1

Initialize the wallet

npx @moneydevkit/agent-wallet@latest init
This generates a mnemonic and saves it to ~/.mdk-wallet/config.json. Back up the mnemonic — it controls your funds.
2

Receive a payment

npx @moneydevkit/agent-wallet@latest receive 1000
Returns a BOLT11 invoice. The daemon auto-starts and polls for incoming payments.
3

Send a payment

npx @moneydevkit/agent-wallet@latest send user@getalby.com 500
Supports bolt11, bolt12, LNURL, and Lightning addresses.
4

Check your balance

npx @moneydevkit/agent-wallet@latest balance

​
How it works

The CLI automatically starts a daemon on first command. The daemon:
  • Runs a local HTTP server on localhost:3456
  • Polls for incoming payments every 30 seconds
  • Persists payment history to ~/.mdk-wallet/
No lightning infrastructure needed — the daemon handles everything locally.

​
Commands

CommandDescription
initGenerate mnemonic, create config
init --showShow config (mnemonic redacted)
init --network signetInitialize on signet testnet
startStart the daemon
stopStop the daemon
restartRestart the daemon
statusCheck if daemon is running
balanceGet balance in sats
receive <amount>Generate BOLT11 invoice
receiveGenerate variable-amount invoice
receive <amount> --description "..."Invoice with custom description
receive-bolt12Generate BOLT12 offer (variable amount)
send <destination> [amount]Pay bolt11, bolt12, LNURL, or Lightning address
paymentsList payment history

​
Output format

All commands output JSON to stdout. Exit code 0 means success, 1 means error. 
$ npx @moneydevkit/agent-wallet@latest balance
{"balance_sats":50000}

$ npx @moneydevkit/agent-wallet@latest receive 1000
{"invoice":"lnbc10n1...","payment_hash":"abc123...","expires_at":"2024-01-15T12:00:00.000Z"}

$ npx @moneydevkit/agent-wallet@latest send user@example.com 500
{"payment_hash":"def456..."}

​
Supported destinations

The send command auto-detects the destination type:
FormatExample
Bolt11lnbc..., lntb..., lntbs...
Bolt12lno...
LNURLlnurl...
Lightning Addressuser@domain.com
Amount is optional for bolt11 invoices that already include an amount.

​
Configuration

Config is stored in ~/.mdk-wallet/config.json: 
{
  "mnemonic": "word word word ...",
  "walletId": "uuid"
}
Environment variable overrides:
VariableDescription
MDK_WALLET_MNEMONICOverride mnemonic
MDK_WALLET_PORTServer port (default: 3456)

​
AI agent integration

This wallet is designed for AI agents that need to send and receive Lightning payments. Every command outputs JSON for easy parsing, and the daemon auto-starts on first use.

​
Paying L402 endpoints

The agent wallet pairs naturally with L402 pay-per-call APIs. Simply pay the invoice and return the token and preimage to unlock the API.

​
Upgrading

# Stop the running daemon
npx @moneydevkit/agent-wallet@latest 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.

​
Troubleshooting

If the wallet becomes unresponsive (commands hang or return no output), restart the daemon: 
npx @moneydevkit/agent-wallet@latest restart
init will refuse to overwrite an existing wallet. To reinitialize, stop the daemon and delete ~/.mdk-wallet/ first. Back up your mnemonic before deleting — it controls your funds.