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, gated by a bearer token
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`)

Local API security

The daemon’s local HTTP API is authenticated. Every route requires a bearer token from ~/.mdk-wallet/auth.token (mode 0600, minted on first use), and requests that do not come from local tooling get 401 UNAUTHORIZED. The CLI handles this for you. Guard auth.token like the mnemonic: whoever reads it can spend the balance. It is not a boundary against code running as your own user, which can read the mnemonic in the same directory. After upgrading, run restart so the new binary serves the API.

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

Local API security

AI agent integration

Paying L402 endpoints

Upgrading

Troubleshooting

​Quick start

​How it works

​Commands

​Output format

​Supported destinations

​Configuration

​Local API security

​AI agent integration

​Paying L402 endpoints

​Upgrading

​Troubleshooting

Quick start

How it works

Commands

Output format

Supported destinations

Configuration

Local API security

AI agent integration

Paying L402 endpoints

Upgrading

Troubleshooting