MCP Server
Model Context Protocol server for ln.bot — your AI agent discovers and calls Lightning wallet tools natively.
Model Context Protocol — your AI agent discovers and calls ln.bot tools natively.
- Discovery:
https://ln.bot/.well-known/mcp.json - Server:
https://api.ln.bot/mcp - Transport: streamable-http
Client Config
Add to your MCP client config (Claude, Cursor, etc.):
{
"mcpServers": {
"lnbot": {
"type": "url",
"url": "https://api.ln.bot/mcp",
"headers": {
"Authorization": "Bearer key__..."
}
}
}
}Tools
get_wallet
Get wallet balance and summary.
Returns: Balance, on-hold amount, available balance, total credits/debits, invoice/payment/transaction counts, and creation date.
create_invoice
Create a Lightning invoice to receive sats.
| Parameter | Type | Required | Description |
|---|---|---|---|
amount | integer | yes | Amount in sats (1 to 1,000,000,000) |
reference | string | no | Optional tracking reference (max 256 chars) |
memo | string | no | Optional memo embedded in the BOLT11 invoice (max 256 chars) |
Returns: Invoice number, bolt11 string, amount, expiry timestamp, and memo.
send_payment
Send sats to a Lightning address, LNURL, or BOLT11 invoice.
| Parameter | Type | Required | Description |
|---|---|---|---|
target | string | yes | Lightning address (user@domain), LNURL (lnurl1...), or BOLT11 invoice |
amount | integer | no | Amount in sats (required for addresses/LNURLs, optional for BOLT11) |
maxFee | integer | no | Max routing fee in sats (default 10, max 10,000; ignored for internal transfers) |
reference | string | no | Optional tracking reference (max 256 chars) |
Returns: Payment number, status, amount, fee, destination, settlement time.
list_invoices
List invoices (newest first).
| Parameter | Type | Required | Description |
|---|---|---|---|
after | integer | no | Return invoices with number less than this (for pagination) |
limit | integer | no | Number to return (default 10, max 50) |
Returns: Paginated invoice summaries with number, status, amount, bolt11, memo, and timestamps.
list_payments
List payments (newest first).
| Parameter | Type | Required | Description |
|---|---|---|---|
after | integer | no | Return payments with number less than this (for pagination) |
limit | integer | no | Number to return (default 10, max 50) |
Returns: Paginated payment summaries with number, status, amount, destination, fee, and timestamps.
list_transactions
List transaction history (newest first).
| Parameter | Type | Required | Description |
|---|---|---|---|
after | integer | no | Return transactions with number less than this (for pagination) |
limit | integer | no | Number to return (default 10, max 50) |
Returns: Paginated transaction history with number, type (credit/debit), amount, balance after, and timestamps.
list_addresses
List the wallet's Lightning addresses.
Returns: Lightning addresses in user@domain format with type (random or vanity).
buy_address
Buy a vanity Lightning address (name@ln.bot).
| Parameter | Type | Required | Description |
|---|---|---|---|
address | string | yes | Vanity address to claim (3-20 lowercase alphanumeric chars) |
Returns: Confirmation with claimed address and cost. Pricing: 3 chars = 10,000 sats, 4 chars = 1,000 sats, 5+ chars = 100 sats.
create_l402_challenge
Create an L402 challenge for pay-per-use API access.
| Parameter | Type | Required | Description |
|---|---|---|---|
amount | integer | yes | Amount in sats (1 to 1,000,000,000) |
description | string | no | Optional description embedded in the invoice (max 256 chars) |
expirySeconds | integer | no | Optional token expiry in seconds (adds an expiry caveat) |
caveats | string | no | Optional comma-separated caveats (e.g., 'service=api,tier=premium') |
Returns: Macaroon, invoice, payment hash, expiry, caveats, and pre-formatted WWW-Authenticate header value.
pay_l402_challenge
Pay an L402 challenge and get a ready-to-use Authorization header.
| Parameter | Type | Required | Description |
|---|---|---|---|
wwwAuthenticate | string | yes | The WWW-Authenticate header value from the 402 response |
maxFee | integer | no | Maximum routing fee in sats (default 10) |
wait | boolean | no | Wait for settlement (default true) |
Returns: Ready-to-use Authorization header (L402 <macaroon>:<preimage>), payment hash, amount, fee, and status.
verify_l402_token
Verify an L402 authorization token.
| Parameter | Type | Required | Description |
|---|---|---|---|
authorization | string | yes | Full Authorization header: 'L402 <base64_macaroon>:<hex_preimage>' |
Returns: Validity status, payment hash, parsed caveats, and error (if any). Checks macaroon signature, preimage proof-of-payment, and caveat validity.