To set a spending limit on your AI agent's Bitcoin wallet on Lightning Faucet, create the agent with a budget (lw create-agent "Research Bot" --budget 5000) or add one later with the update_agent action and a budget_limit_sats value. Once the agent's total spending reaches that number, every further payment fails with a budget_exceeded error (HTTP 402) before a single sat leaves the wallet. Pair that cap with a small funded balance and you have two independent ceilings on what the agent can ever spend.
That is the short answer. The rest of this guide covers what we have learned from running the agent wallet platform ourselves: how the operator and agent keys are separated, why the funded balance is your first limit and the budget is your second, what the rate limit and pause switch are for, how to claw sats back, and what to do in the first five minutes if an agent key leaks. Every control described here is live in the Lightning Faucet agent API; nothing is hypothetical.
What a spending limit means for an AI agent wallet
The definition we use
An AI agent spending limit is a hard, server side ceiling on how many sats an autonomous program can send, enforced by the wallet provider rather than by the agent's own prompt or code. The distinction matters. An instruction like "never spend more than 5,000 sats" inside a system prompt is a suggestion to a language model. A budget_limit_sats value stored against the agent's wallet is a rule the payment path checks before it pays anything. The agent cannot talk its way past it, and neither can a malicious API response that tries to convince the agent to overpay.
Why this is the first question operators ask
The biggest hesitation people have before handing an AI agent real money is runaway spend. An agent in a retry loop, a paid API that suddenly charges more per call, or a prompt injection that tells the agent to pay an attacker's invoice can all drain a wallet faster than a human would notice. On Lightning, payments settle in seconds, so "I'll check the logs tomorrow" is not a control. The controls have to be in place before the agent sends its first payment.
Layer one: the operator and agent hierarchy
Two kinds of keys, two kinds of wallets
Lightning Faucet splits every account into an operator and one or more agents. The operator is you, the human or the platform, and holds a master API key that starts with lf_. The operator balance is the main pot of sats. Each agent you create gets its own sub-wallet, its own balance, and its own API key that starts with agent_.
The agent key can pay invoices, call L402 APIs, send to Lightning addresses, keysend, and create invoices to receive. It cannot create other agents, fund itself, withdraw the operator balance, or touch any other agent's wallet. So the blast radius of any single agent is exactly its own balance.
Why this matters in practice
Give each agent, or each job, its own sub-wallet. A research bot that buys data from L402 APIs should not share a wallet with a trading bot that places prediction market positions. If one misbehaves, the other keeps running, and you can see exactly which one spent what in its own transaction history. Never give an agent your lf_ operator key. The agent key is the one that belongs in the agent's environment.
Layer two: the funded balance is a ceiling
fund_agent only moves what you choose
A new agent starts with nothing. It can only spend sats you move into it with fund_agent, which transfers from the operator balance to the agent. That means the simplest and strongest spending limit you have is the balance itself. An agent holding 2,000 sats cannot spend 2,001, no matter what its budget says.
curl -X POST https://lightningfaucet.com/api/agents \
-H "Authorization: Bearer lf_xxx" \
-H "Content-Type: application/json" \
-d '{"action": "fund_agent", "agent_id": 123, "amount_sats": 2000}'Fund per task, not per month
The pattern we recommend is to fund for the job in front of the agent rather than for a whole quarter. If a research task needs roughly 20 paid API calls at 50 sats each, fund around 1,000 to 1,500 sats and top up when it runs low. The operator balance stays where the agent cannot reach it. You can deposit to the operator account over Lightning and deposits are free, so small, frequent top ups cost you nothing but a moment of attention.
Layer three: set a budget with budget_limit_sats
Setting the budget at creation
The budget is a cap on the agent's cumulative spending, tracked as total_spent on the agent record. You can set it the moment you create the agent. With the lw command line tool:
lw create-agent "Research Bot" --budget 5000Or through the API, by passing budget_limit_sats in the create_agent request. Leave it out and the agent has no budget cap, in which case only its balance limits it.
Changing the budget later with update_agent
The update_agent action lets the operator change an agent's name, description, budget, rate limit, and active status. To raise or lower the cap:
curl -X POST https://lightningfaucet.com/api/agents \
-H "Authorization: Bearer lf_xxx" \
-H "Content-Type: application/json" \
-d '{"action": "update_agent", "agent_id": 123, "updates": {"budget_limit_sats": 5000}}'Because the budget measures total spend rather than a daily window, it does not reset on its own. When an agent reaches its cap, that is a deliberate checkpoint: you review what it bought, then raise the budget if the spending made sense.
What happens when the agent hits the cap
Before any debit, Lightning Faucet compares the cost of the payment with the budget remaining. If the payment would push spending past the cap, it is refused with budget_exceeded and HTTP status 402, and the sats stay in the agent wallet. This gate covers every outgoing path: L402 API calls, BOLT11 invoice payments, keysend, and Lightning address payments. Prediction market stakes and arena buy ins placed from an agent balance count toward the same budget_limit_sats, and a refused bet returns the stake to the agent and does not count against the budget.
There is one more guard that surprises people the first time they see it. If an agent has a budget, fund_agent will refuse a transfer that would leave the agent's balance above its budget limit. You cannot accidentally park 50,000 sats in a wallet you capped at 5,000.
Reading budget_remaining_sats
The agent can check itself at any time with the balance action. The response includes budget_remaining_sats, which is null when the agent has no budget cap. A well behaved agent should read this before starting an expensive task and stop cleanly, rather than failing halfway through, when the remaining budget is too small.
Layer four: rate limits and the pause switch
Per agent rate limits
Budgets cap how much an agent spends. Rate limits cap how fast. Each agent has its own rate_limit_per_minute, which the operator sets with update_agent. The agent can call the rate_limit action to see where it stands. A tight rate limit is your defense against a retry loop: even if a bug makes the agent hammer a paid API, it can only do so a fixed number of times per minute, which buys you time to notice.
For prediction market bets specifically, there is also a platform rate limit of ten bets per minute per agent, returned as rate_limited with HTTP 429.
Pausing an agent instantly
If something looks wrong, deactivate the agent with update_agent and "is_active": 0 in the updates object. Every payment path checks that the agent is active, so a paused agent cannot spend, even with a valid key. Flip it back to 1 when you have figured out what happened. Pausing is the fastest control you have and it does not require you to move any funds first.
Layer five: pulling sats back and rotating keys
withdraw_from_agent
When a task is done, or when you do not trust an agent anymore, use withdraw_from_agent with the agent_id and an amount_sats to pull sats back into the operator balance. Idle sats sitting in an agent wallet are exposure with no purpose. Sweeping them back after each job keeps the funded balance, your first layer, close to zero between runs.
regenerate_agent_key if a key leaks
Agent keys end up in places they should not: a committed .env file, a log line, a shared screenshot. If you suspect an agent_ key has leaked, call regenerate_agent_key. The old key stops working immediately and a new one is issued. The new key also carries a 30 minute payment cooldown, so even if an attacker somehow obtained the fresh key at the same moment, they cannot spend with it straight away. The operator key has its own regenerate_operator_key action with a 60 minute withdrawal cooldown.
Our incident order is simple: pause the agent, withdraw its balance, rotate the key, then investigate.
Layer six: watch it with webhooks
The two events that matter for spending control
Lightning Faucet can POST events to your own HTTPS endpoint. Register one with register_webhook (up to five per agent or operator). For spending control, subscribe to at least these two:
payment_failed: an outgoing payment failed, including payments blocked by the budget. If you see a burst of these, the agent is trying to spend past its cap.budget_warning: the agent is approaching its budget limit. It fires as spending crosses 80, 90, 95 and 99 percent ofbudget_limit_sats, so you get a heads up before the cap bites rather than after.
balance_low and payment_completed are useful too if you want a running feed of what the agent is buying.
Verify the signature
Every delivery carries an X-Webhook-Signature header. Compute an HMAC SHA256 of the timestamp plus the body with the secret you received at registration, and compare. The secret is only shown once, so store it when you register. Do not act on an unsigned or mismatched webhook, especially if the action is "raise the budget."
Doing it from Claude with MCP
Install the wallet server
If you run your agent inside Claude, the lightning-wallet-mcp server exposes the same operator and agent tools. Add it with one command:
claude mcp add lightning-wallet -- npx -y lightning-wallet-mcpThen, working with your operator key, ask in plain language: "Create an agent called Research Bot with a budget of 5000 sats, and fund it with 1000 sats." Claude calls create_agent and fund_agent for you and hands back the new agent key. Our Claude and MCP setup guide walks through the install and key handling step by step.
Switch to the agent key for spending
After setup, switch Claude to the agent credentials before it starts paying for things. That way the model is holding a key whose worst case is capped by the balance and the budget, not your operator key.
A practical setup checklist
Start small, then widen
Here is the arc we suggest for any new agent:
- Create one agent per job with a budget from day one, for example 5,000 sats.
- Fund it for the task in front of it, well under the budget.
- Set a per minute rate limit that matches how often the job should really pay.
- Register a webhook for
payment_failedandbudget_warning. - Keep the
agent_key in the agent's environment only. Thelf_key stays with you. - After the job,
withdraw_from_agentto sweep leftover sats back. - Rotate the agent key on any suspicion of exposure, and pause first if in doubt.
What the limits do not do
Be clear about the edges. The budget is a cumulative total, not a daily allowance, and Lightning Faucet does not offer per merchant allowlists or a human approval step on each payment. If you need those, build them in your own code on top of the webhooks. The limits here are about capping total exposure, which is the problem most operators actually have.
What it costs
Deposits are free. L402 payments carry a 1% platform fee, rounded down, and calls under 100 sats carry no platform fee at all, so the small, frequent payments agents typically make are cheap to cap and cheap to run.
Where to put a capped agent to work
Real things an agent can pay for
Once the guardrails are in place, a capped agent can call paid L402 APIs, pay invoices, and settle with other agents. It can also take positions on Lightning Faucet prediction markets straight from its own balance, with every stake counted against its budget. If you are building your own paid service for agents to buy, the builder tools are the place to start. And the AI agents overview has the full picture of what an agent wallet can do.
The one line summary
Give each agent its own wallet, fund it for the task, set budget_limit_sats, watch budget_warning, and keep your operator key to yourself. That combination turns "what if my agent spends everything" into a question with a small, known answer.