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
Initialize the wallet
npx @moneydevkit/agent-wallet@latest init
~/.mdk-wallet/config.json. Back up the mnemonic — it controls your funds.Receive a payment
npx @moneydevkit/agent-wallet@latest receive 1000
Send a payment
npx @moneydevkit/agent-wallet@latest send user@getalby.com 500
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
| Command | Description |
|---|
init | Generate mnemonic, create config |
init --show | Show config (mnemonic redacted) |
init --network signet | Initialize on signet testnet |
start | Start the daemon |
stop | Stop the daemon |
restart | Restart the daemon |
status | Check if daemon is running |
balance | Get balance in sats |
receive <amount> | Generate BOLT11 invoice |
receive | Generate variable-amount invoice |
receive <amount> --description "..." | Invoice with custom description |
receive-bolt12 | Generate BOLT12 offer (variable amount) |
send <destination> [amount] | Pay bolt11, bolt12, LNURL, or Lightning address |
payments | List payment history |
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:
| Format | Example |
|---|
| Bolt11 | lnbc..., lntb..., lntbs... |
| Bolt12 | lno... |
| LNURL | lnurl... |
| Lightning Address | user@domain.com |
Configuration
Config is stored in ~/.mdk-wallet/config.json:
{
"mnemonic": "word word word ...",
"walletId": "uuid"
}
| Variable | Description |
|---|
MDK_WALLET_MNEMONIC | Override mnemonic |
MDK_WALLET_PORT | Server 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 MDK402 endpoints
The agent wallet pairs naturally with MDK402 pay-per-call APIs. Simply pay the invoice and return the 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
~/.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.
