Agent Wallet

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

This generates a mnemonic and saves it to ~/.mdk-wallet/config.json. Back up the mnemonic — it controls your funds.

Receive a payment

npx @moneydevkit/agent-wallet@latest receive 1000

Returns a BOLT11 invoice. The daemon auto-starts and polls for incoming payments.

Send a payment

npx @moneydevkit/agent-wallet@latest send user@getalby.com 500

Supports bolt11, bolt12, LNURL, and Lightning addresses.

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

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:

Format	Example
Bolt11	`lnbc...`, `lntb...`, `lntbs...`
Bolt12	`lno...`
LNURL	`lnurl...`
Lightning Address	`user@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:

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 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.

Overview

Integrations

Agents

Examples

moneydevkit.com Dashboard

Quick start

How it works

Commands

Output format

Supported destinations

Configuration

AI agent integration

Paying L402 endpoints

Upgrading

Troubleshooting

​Quick start

​How it works

​Commands

​Output format

​Supported destinations

​Configuration

​AI agent integration

​Paying L402 endpoints

​Upgrading

​Troubleshooting

Quick start

How it works

Commands

Output format

Supported destinations

Configuration

AI agent integration

Paying L402 endpoints

Upgrading

Troubleshooting