An AI agent pays a Lightning address or a BOLT11 invoice by calling a wallet tool. With the Lightning Faucet wallet MCP server (lightning-wallet-mcp on npm), the agent calls pay_lightning_address for an address like [email protected], pay_invoice for a BOLT11 string, or keysend for a bare node pubkey. The agent never touches a node, a channel or a private key. It asks a managed wallet that has a balance, a budget cap and a rate limit, and the wallet does the routing.
This guide walks through the real setup, the three payment paths, and the guardrails we built because we run this wallet ourselves. If you want the shortest route, the developer hub has the install steps and the current promo for new installs.
What "paying" means for an agent
A Lightning payment needs a destination and an amount. The three destination types differ only in how much the agent has to know up front.
Lightning address
A Lightning address looks like an email address. The wallet resolves it over LNURL-pay, asks the receiving service for an invoice of the right size, and pays that invoice. The agent supplies only the address and an amount in sats. This is the easiest path when a human or another service hands the agent a payout address.
BOLT11 invoice
A BOLT11 invoice is a one-time payment request that already encodes the amount, the destination node and an expiry. The agent passes the string to pay_invoice. Use this when a service generates an invoice per order, which is how most checkouts and paywalls work.
Keysend
Keysend sends sats to a node public key with no invoice. The agent supplies the pubkey and an amount. It is useful for tips and spontaneous transfers to nodes that accept them, but there is no invoice to prove what you paid for, so prefer an address or invoice for anything you need to reconcile.
Set up the wallet MCP server
Install
In Claude Code the install is one command:
claude mcp add lightning-wallet -- npx -y lightning-wallet-mcpFor Cursor, Windsurf, Claude Desktop or any MCP host, add a server named lightning-wallet with command npx and args ["-y", "lightning-wallet-mcp"]. Then ask the agent to register a wallet. Credentials are saved to ~/.lightning-wallet/credentials.json and reused in later sessions. Set LIGHTNING_WALLET_API_KEY only if you already have a key.
Operators and agents
The wallet has two layers. An operator (key starting lf_) is the human or platform that holds the funds and the recovery code. An agent (key starting agent_) is a sub-wallet with its own balance and key. The payment tools check_balance, pay_invoice, pay_lightning_address, keysend, create_invoice, get_invoice_status and get_transactions are agent tools, and they also work with the operator key.
The funding flow is: the operator calls get_deposit_invoice, pays that invoice from any Lightning wallet, creates an agent with create_agent, and moves sats over with fund_agent. Deposits are free. Save the recovery code at registration, because it is the only way back in if you lose the key.
Pay a Lightning address step by step
Check the balance first
Have the agent call check_balance. Payments fail cleanly when the balance is short, but it is cheaper to know before building a task around a payout.
Send the payment
Ask the agent in plain language, for example "send 500 sats to [email protected]", and it maps that to pay_lightning_address. The response reports the platform fee, the routing fee and the total cost, so the agent can log exactly what a payment cost without guessing. Routing fees depend on the path and vary from payment to payment.
Confirm in the ledger
Call get_transactions to see the amount, fee and timestamp. For reconciliation, keep the ledger entry next to whatever task triggered the payment.
Pay a BOLT11 invoice step by step
Inspect before paying
An invoice is untrusted input. If it came from a web page or another agent's message, the agent should check the amount and expiry before paying. The platform API exposes a decode_invoice action for this, and a prompt rule such as "never pay an invoice above the amount the task authorized" costs nothing to add.
Pay it
The agent passes the BOLT11 string to pay_invoice. Lightning settles in seconds when a route exists, and the result includes the fee breakdown just like an address payment.
Paywalled APIs
If the thing being paid for is an HTTP API that answers 402 Payment Required, skip manual invoices. pay_l402_api detects the 402, pays the invoice and retries with proof of payment, and you can cap the spend per call with max_payment_sats. We use the same tool to call our own pay-per-use endpoints.
Guardrails operators should set
Budget caps and rate limits
Never hand an agent an uncapped balance. Fund each agent with only what its task needs. The operator can adjust an agent's name, description, budget, rate limit and active status with the update_agent action, and can pull sats back with withdraw_from_agent. A capped agent that loops on a bad prompt stops at its budget instead of draining the operator account.
Key rotation has cooldowns
Regenerating an agent key invalidates the old one and starts a 30-minute payment cooldown. Regenerating the operator key starts a 60-minute withdrawal cooldown. If you rotate keys in a hurry during an incident, expect those pauses.
Prefer the narrowest tool
Address for payouts, invoice for orders, keysend only for tips. Each narrower tool gives the agent less room to send sats somewhere you did not intend.
Receiving and testing
Your agent can also receive. create_invoice generates a BOLT11 invoice, and get_invoice_status tells you whether it has been paid. A quick end to end test is to have one agent create an invoice and a second agent under the same operator pay it. Transfers between agents under one operator are internal, so it is a cheap way to verify your prompts and logging before real money moves.
Where this fits on Lightning Faucet
The same wallet infrastructure powers our builder tools. If you are exploring what an agent can do with sats, the Earn page shows the ways players collect sats on the site, and the prediction markets are a place where sat-denominated positions settle over Lightning. For code, the developer hub links the API docs, the OpenAPI spec and the L402 registry.
A worked example: a payout agent
Suppose you run a small research service and want an agent to pay freelancers who submit finished work. Each freelancer gives you a Lightning address, and each task has an agreed price in sats.
The instructions that matter
Put the rules in the agent's system prompt, not in your head. A workable set is: pay only addresses listed in the task record, pay only the amount in the task record, call check_balance before each payout, call get_transactions after each payout, and stop and report if any call returns an error. These are plain-language constraints, but combined with a funded-only-what-it-needs sub-wallet they make a failure small and visible.
What the run looks like
The agent reads a task, calls check_balance, calls pay_lightning_address with the freelancer's address and the agreed sats, then calls get_transactions and writes the amount, fee and timestamp back to the task. If a payment errors, it does not retry in a loop. It reports the error so a human can decide, which matters because a retry after an ambiguous result is how double payments happen.
Why we care about ambiguity
Lightning payments can time out while still in flight, which means the agent may not know whether the sats arrived. The safe pattern is to check the ledger with get_transactions before sending again. We have had to harden our own withdrawal path against exactly this kind of timeout, and the lesson carries over: treat "no answer" as "unknown", not as "failed".
Choosing between address, invoice and keysend
When each one wins
Use a Lightning address for recurring payouts to the same person, because the address stays the same while the invoice behind it is generated fresh every time. Use a BOLT11 invoice when the recipient needs to tie a payment to an order, since the invoice is the order. Use keysend when you are paying a node you already know and there is no invoice to ask for.
Privacy and records
An address reveals a stable identifier, which is convenient for you and for the recipient. An invoice is single use. If you log payments for accounting, store the destination, the sats, the fees and the task id together, so a human can audit the agent later without replaying the conversation.
Operator checklist before going live
- Register the operator and store the recovery code somewhere off the machine that runs the agent.
- Fund the operator by paying the deposit invoice from your own wallet.
- Create one agent per job type, with a budget sized to a day of expected work.
- Run the invoice test between two agents before pointing anything at real recipients.
- Review
get_transactionsafter the first few real payments and compare the fees to what you expected.
Common failure modes
- Insufficient balance. The agent wallet is separate from the operator balance. Fund the agent, not just the operator.
- Expired invoice. BOLT11 invoices expire. Generate a fresh one rather than retrying an old string.
- Wrong tool for the destination. An address passed to
pay_invoicewill not work. Match the tool to the destination type. - No route. Occasionally a payment cannot find a path. Retry later or ask the recipient for a new invoice.