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

# Agent Wallet

> Self-custodial Lightning wallet for AI agents. No API keys required.

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.

<Info>
  The agent wallet runs a local daemon that leverages moneydevkit's lightning infrastructure. No node management required.
</Info>

## Quick start

<Steps>
  <Step title="Initialize the wallet">
    ```bash theme={null}
    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.
  </Step>

  <Step title="Receive a payment">
    ```bash theme={null}
    npx @moneydevkit/agent-wallet@latest receive 1000
    ```

    Returns a BOLT11 invoice. The daemon auto-starts and polls for incoming payments.
  </Step>

  <Step title="Send a payment">
    ```bash theme={null}
    npx @moneydevkit/agent-wallet@latest send user@getalby.com 500
    ```

    Supports bolt11, bolt12, LNURL, and Lightning addresses.
  </Step>

  <Step title="Check your balance">
    ```bash theme={null}
    npx @moneydevkit/agent-wallet@latest balance
    ```
  </Step>
</Steps>

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

```bash theme={null}
$ 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`:

```json theme={null}
{
  "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](/l402) pay-per-call APIs. Simply pay the invoice and return the token and preimage to unlock the API.

## Upgrading

```bash theme={null}
# 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:

```bash theme={null}
npx @moneydevkit/agent-wallet@latest restart
```

<Warning>
  `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.
</Warning>