MCP server

Every wallet has its own Model Context Protocol server. An agent connected to it can check the balance, create invoices, price and send payments, list its history, buy an address and handle L402, through the 12 tools below.

• Server: https://api.ln.bot/v1/wallets/{walletId}/mcp
• Transport: streamable HTTP
• Auth: Authorization: Bearer <key>
• Discovery: https://ln.bot/.well-known/mcp.json, the server card agents and clients can find ln.bot by

The tools have no spending limit of their own: send_payment and pay_l402_challenge can spend the whole balance. Give an agent a wallet that holds only what it may spend, and keep the rest in another wallet. Creating wallets, rotating keys, webhooks and backups aren't MCP tools; use the CLI, an SDK or the REST API for those.

Client config

A client needs the wallet's ID for the URL and a key for the header. lnbot init created both: lnbot whoami shows the wallet ID, and the key is in ~/.config/lnbot/config.json (lnbot key show prints it). Without the CLI, POST /v1/register returns the keys and POST /v1/wallets the wallet ID; see getting started with the API.

The CLI prints a ready block for the active wallet, or for another with --wallet:

$ lnbot mcp config --remote
Add to your MCP client config:

{
  "mcpServers": {
    "lnbot": {
      "headers": {
        "Authorization": "Bearer uk_9Qf3Lx7TzM2pW8vR4kNs6bHc"
      },
      "type": "url",
      "url": "https://api.ln.bot/v1/wallets/wal_c7i0hnuoxxupuwej/mcp"
    }
  }
}

The key in that header is the account's primary user key (uk_), which reaches every wallet on the account, so treat the file you paste it into like the key itself. For an agent, put that wallet's own key (wk_..., from w.key.create()) in the header instead: it reaches that wallet and no other. With a wallet key, the URL can also be https://api.ln.bot/v1/wallets/current/mcp. Clients differ in the shape they want around the URL and the header.

Claude Code

claude mcp add --transport http lnbot https://api.ln.bot/v1/wallets/wal_.../mcp \
  --header "Authorization: Bearer uk_..."

That stores the server for you in the current project; --scope user makes it available in every project. Claude Code's own config files describe this kind of server with "type": "http", so add it with the command rather than pasting the block above. See Claude Code's MCP docs.

Cursor

Put this in .cursor/mcp.json in your project, or in ~/.cursor/mcp.json for every project:

{
  "mcpServers": {
    "lnbot": {
      "url": "https://api.ln.bot/v1/wallets/wal_.../mcp",
      "headers": {
        "Authorization": "Bearer ${env:LNBOT_API_KEY}"
      }
    }
  }
}

Cursor fills in ${env:LNBOT_API_KEY} from your environment, which keeps the key out of the file; writing the key in directly works too. See Cursor's MCP docs.

Other clients

Any client that speaks streamable HTTP and can send a header can connect: add the URL and the Authorization: Bearer header in its MCP settings.

Tools

The parameter descriptions below are the ones the server gives agents.

get_wallet

Get wallet balance and summary. No parameters.

Returns the balance, the on-hold amount, the available balance, and invoice, payment and transaction counts.

create_invoice

Create a Lightning invoice to receive sats.

Returns the invoice number, bolt11 string, amount and expiry.

quote_payment

Price a payment without sending it. Read-only: nothing is sent or held.

Returns what GET .../payments/resolve does: whether the recipient is an ln.bot wallet (internal, no fees), the network fee estimate, the service fee, the total, and without an amount the most the wallet can send there now. A fee warning means send_payment without maxFee would be rejected. Pricing a Lightning address or LNURL fetches an invoice from the recipient, so it takes a moment longer.

send_payment

Send sats to a Lightning address (user@domain), LNURL, or BOLT11 invoice. This sends real money: the amount and the fees are placed on hold until the payment settles.

Leave maxFee out unless quote_payment returned a fee warning. A payment out to Lightning also pays the 0.25% service fee, at least ₿1; between ln.bot wallets there are no fees.

list_invoices

List invoices (newest first).

Returns invoice summaries with status, amount and bolt11.

list_payments

List payments (newest first).

Returns payment summaries with status, amount and destination.

list_transactions

List transaction history (newest first).

Returns each transaction's type, amount and the balance after it.

list_addresses

List the wallet's Lightning addresses, in user@domain format. No parameters.

buy_address

Buy a vanity Lightning address (name@ln.bot). It costs ₿100 for five characters or more, ₿1,000 for four and ₿10,000 for three, deducted from the wallet's balance.

create_l402_challenge

Create an L402 challenge (an invoice and a macaroon) for pay-per-use API access.

Returns the macaroon, the invoice and a ready-made WWW-Authenticate header value for the 402 response.

pay_l402_challenge

Pay an L402 challenge and get a ready-to-use Authorization header (L402 <macaroon>:<preimage>). The tool parses the WWW-Authenticate header, pays the invoice and waits for settlement.

There is no price limit: the tool pays whatever the invoice asks. The L402 clients for TypeScript and C# check the invoice's amount against a limit you set before paying.

verify_l402_token

Verify an L402 authorization token.

Checks the macaroon signature, the preimage (proof of payment) and the caveats.