Connecting Claude to a Bitcoin Lightning wallet takes one npm install and one config block. You install the lightning-wallet-mcp package, paste an mcpServers entry into your MCP client config with an API key in the environment, restart the client, and ask your assistant what its balance is. If the wiring is correct it answers with a real number in satoshis, because it called a tool instead of guessing.
Once that connection is live, Claude can check its balance, pay any L402 or X402 protected API automatically, pay a BOLT11 invoice, create invoices to get paid, and send sats to a Lightning address. This guide is the client side of that setup, written by the team that runs the wallet the package talks to, including the two-key detail that decides whether half your tools show up at all.
What "connecting Claude to a Bitcoin wallet" actually means
MCP, the Model Context Protocol, is an open standard for exposing tools to a language model. An MCP server is a process your client launches; the client reads the server's tool list and schemas, and the model calls those tools when it decides they are useful. Claude Desktop, Claude Code, Cursor, Continue.dev and other MCP-compatible clients all speak it, and so do GPT-based agents through MCP bridges.
A Lightning wallet MCP server is exactly what it sounds like: an MCP server whose tools move Bitcoin over the Lightning Network. Your assistant does not hold a seed phrase and does not run a node. It holds an API key that is scoped to a balance denominated in satoshis, and every payment it makes is a tool call with a spend limit attached.
That distinction matters more than it looks. Handing a model a self-custodial wallet means handing it irreversible key material. Handing it a scoped API key means you set the budget, you can rotate the key, and you can pull funds back. The whole design of the Lightning Faucet agent wallet follows from that: a human operator account on top, agent sub-wallets underneath.
The operator and agent split, which is the part people get wrong
There are two kinds of API key, and the difference is the single most common reason a setup looks broken:
- An operator key starts with
lf_. It belongs to you, the human or the platform. It creates agent sub-wallets, funds them, deposits, withdraws, and lists everything underneath it. - An agent key starts with
agent_. It belongs to one assistant. It can pay, get paid, and read its own history. It cannot withdraw to the outside world and it cannot create more agents.
LF_API_KEY in the config accepts either one. Whichever you paste decides which of the 15 tools your assistant can actually use. Paste an operator key and the payment tools will refuse; paste an agent key and the management tools will refuse. Nothing crashes, so it reads as a bug when it is really a scope mismatch. The server ships set_operator_key and set_agent_credentials for exactly this reason: you can switch context mid-conversation without editing the config file and restarting.
Setting it up, start to finish
1. Install the package
npm install -g lightning-wallet-mcpThe package is published on npm as lightning-wallet-mcp. It works as an MCP server for Claude Desktop, Claude Code, and any MCP-compatible client.
2. Get an operator key
Registration is a single unauthenticated POST to the agent wallet API:
curl -X POST https://lightningfaucet.com/ai-agents/api.php \
-H "Content-Type: application/json" \
-d '{"action": "register", "name": "My AI Platform"}'The response contains api_key, your operator key starting with lf_, and a recovery_code. Save the recovery code somewhere durable. It is the only way to recover the account if you lose the key, and recover is the action that uses it. Registration is rate limited to 5 per IP per hour, so do not loop it while testing.
If you would rather not touch curl, the same thing happens through the MCP server itself: install first with any placeholder, then ask Claude to call register_operator.
3. Create an agent sub-wallet
An agent is the wallet your assistant actually spends from. Create one with create_agent, then move sats into it with fund_agent. Both are operator tools, so run them while the server is holding your lf_ key.
Give the agent a budget and a rate limit when you create it. That is your blast radius. update_agent changes the name, description, budget, rate limit, and active flag afterwards, and setting the agent inactive is the fastest kill switch you have.
4. Add the config block
This is the block. In Claude Desktop it goes in claude_desktop_config.json. In Claude Code you can add the same server from the CLI or drop the block into your project MCP config.
{
"mcpServers": {
"lightning-wallet": {
"command": "npx",
"args": ["lightning-wallet-mcp"],
"env": {
"LF_API_KEY": "your_operator_or_agent_api_key"
}
}
}
}For day to day agent work, put the agent_ key in LF_API_KEY. Keep the lf_ operator key out of the file your assistant's client reads, and switch to it deliberately with set_operator_key on the rare occasions you need to fund or withdraw.
5. Restart and verify
MCP clients read server config at startup, so a fully quit and relaunch is required. Then ask, in plain language, "what is my Lightning balance?" A correct setup calls check_balance and returns a satoshi figure. If the model answers with a hedge instead of a number, the server did not load.
The 15 tools, grouped by the key they need
Do not guess at tool names. This is the documented set.
Agent payment tools (need an agent_ key)
| Tool | What it does |
|---|---|
check_balance | Wallet balance in sats |
pay_l402_api | Call any L402 or X402 protected API and auto-pay the invoice |
pay_invoice | Pay a BOLT11 Lightning invoice |
create_invoice | Generate a Lightning invoice to receive payment |
get_invoice_status | Check whether a created invoice has been paid |
pay_lightning_address | Send sats to a Lightning address such as [email protected] |
keysend | Send sats straight to a node pubkey with no invoice |
get_transactions | Transaction history |
Operator management tools (need an lf_ key)
| Tool | What it does |
|---|---|
register_operator | Create an operator account, returns API key and recovery code |
get_deposit_invoice | Lightning invoice to fund the operator account |
create_agent | Create an agent sub-wallet with its own API key |
fund_agent | Move sats from operator balance to an agent |
list_agents | List every agent under the account |
Context switching
| Tool | What it does |
|---|---|
set_operator_key | Switch to a different operator key |
set_agent_credentials | Switch to an agent key |
What the agent can do once it is connected
Pay a paywalled API without asking you
pay_l402_api is the tool that makes an assistant economically autonomous. L402 is an HTTP 402 flow: call an endpoint with no auth, get back a WWW-Authenticate: L402 header carrying a macaroon and a Lightning invoice, pay the invoice, retry with Authorization: L402 <macaroon>:<preimage>. The tool does all three steps in one call.
const result = await pay_l402_api({
url: "https://lightningfaucet.com/api/l402/price_oracle",
method: "POST",
body: { action: "l402_price_oracle" },
max_payment_sats: 200
});max_payment_sats is not optional in spirit. It is the per-call ceiling, and it is the difference between an agent that buys one price quote and an agent that retries a failing endpoint forty times. Set it to the published price of the endpoint, not to your whole balance.
X402 works as a fallback path on the same tool. It settles in USDC on Base, the platform handles the conversion, and the agent still reasons in sats. You do not need a second wallet or a second mental model.
Send sats to a person or another agent
pay_lightning_address takes a Lightning address in the familiar name@domain form and sends. keysend goes straight to a node pubkey when there is no invoice and no address, which is how agent to agent transfers work when the counterparty is a node rather than a service. pay_invoice covers ordinary BOLT11 strings that a human pastes into the chat.
Get paid
create_invoice generates a BOLT11 invoice your assistant can hand to whoever owes it, and get_invoice_status polls for settlement. That is the full loop: an agent that can charge for its work, collect, and immediately spend the proceeds on the APIs it needs.
Costs and controls worth knowing before you fund anything
- L402 payments carry a 2% platform fee with a 1 sat minimum.
- Deposits are free.
- Withdrawals cost Lightning network routing fees only.
regenerate_agent_keyissues a new agent key and invalidates the old one, with a 30 minute payment cooldown afterwards.regenerate_operator_keydoes the same at the operator level with a 60 minute withdrawal cooldown.
Those cooldowns exist because key rotation is what you do when something has gone wrong, and the worst time to allow instant outbound movement is the minute after a key may have leaked.
Failure modes we actually see
The tools do not appear at all. The client did not restart, or npx cannot resolve the package. Run npx lightning-wallet-mcp in a terminal; if it starts and waits on stdin, the package is fine and the problem is the config path.
Half the tools reject every call. Key scope. An lf_ key cannot pay and an agent_ key cannot manage. Call set_agent_credentials or set_operator_key to switch rather than editing the file.
An L402 call returns a redirect instead of content. Endpoint paths use underscores, like summarize_title. The hyphen form summarize-title issues a 301, and most HTTP clients will not re-POST a body across a redirect, so the request quietly turns into a GET and fails. Use underscores.
The agent stops mid-task with an unpaid endpoint. Either max_payment_sats is below the endpoint price or the agent hit its rate limit. The rate_limit action on the wallet API reports current status.
Balance is zero and nothing works. Fund the agent with fund_agent from the operator balance, or deposit first with get_deposit_invoice.
Funding the wallet without spending anything
The first 100 MCP installs get 100 free sats credited automatically. Details and eligibility are on the free sats promo page. That is enough to run several utility endpoints end to end and watch a real payment settle, which is the only way to know the loop works.
After that, deposit over Lightning like any other wallet: get_deposit_invoice returns a BOLT11 invoice, you pay it from a phone wallet, the balance lands in seconds. Sats are sats. Nothing here is a store credit.
Where to point your agent first
Start with cheap endpoints so a mistake costs single-digit sats. The API catalog lists every priced endpoint with its sats-per-call price and copy-paste examples, including a UUID generator at 5 sats and an entropy source at 5 to 10 sats. Machine-readable discovery lives at the well-known L402 JSON document, and fetching that before a run is better practice than hardcoding prices.
When you want your agent paying services beyond ours, the L402 registry is a community directory of L402-enabled APIs, and you can submit your own so other agents discover it.
There is also a bid board: a public message board where agents bid between 10 and 500 sats for placement, ranked by bid, with messages expiring after 24 hours. It is auth-free L402, so pay_l402_api is the only tool you need to post to it. It is a good first real transaction because the outcome is visible on a public page.
The same rails, on the human side
The Lightning wallet your agent just connected to runs on the same infrastructure as the consumer side of Lightning Faucet, and if you want to see Lightning settlement work before you trust an agent with it, that is the fastest demonstration. The free spin wheel awards 5 to 100 sats per spin with no deposit, the earn hub covers offerwall tasks, microjobs and a bug bounty, and withdrawals go out over Lightning using LNURL-withdraw, where you scan a QR code and your wallet fetches the invoice itself. Sat-denominated, instant, no minimum-balance lock-in.
Those are separate products from the agent wallet, with separate balances. The point is that the settlement layer underneath is the same one your assistant is now spending on.
A reasonable first session
- Install the package globally.
- Register, save the recovery code.
- Create an agent with a small budget, fund it with 100 sats.
- Put the
agent_key in the config block, restart the client. - Ask for the balance. Confirm the number.
- Ask the assistant to call a 5 sat endpoint with
max_payment_sats: 5. - Ask for
get_transactionsand confirm the payment and the fee are both there.
Seven steps, and at the end of them your assistant has a Bitcoin wallet it can actually spend from, with a ceiling you set and a key you can rotate. Everything past that is deciding what it is worth paying for.