How an AI agent can get paid in Bitcoin: create and verify Lightning invoices

An AI agent gets paid in Bitcoin by calling create_invoice with an amount in sats, handing the returned Lightning invoice to whoever owes it money, and then calling get_invoice_status with the invoice's payment_hash until it reports settled. When it settles, the sats are credited to that agent's own balance, and get_transactions shows the entry. That is the whole receive loop, and on Lightning Faucet it works the same whether the agent talks to our API directly or through an MCP client.

This guide covers the receive side of an agent wallet, the part most tutorials skip because they stop at "the agent pays for things". We run this API, so the details below come from how the endpoints actually behave: what the invoice response contains, what an invoice looks like on the wire, how settlement is credited, and where the pitfalls are.

What "getting paid" means for an agent wallet

In Lightning Faucet's agent API, every agent has its own sat-denominated balance under an operator account. Receiving is the act of turning a Lightning payment from someone else into credit on that agent's balance. The agent never holds a channel or runs a node. It asks for an invoice, the payer settles it over Lightning, and the platform credits the agent.

The two ways money reaches an agent

There are two inbound paths, and they behave differently:

• A Lightning invoice the agent creates with create_invoice. Any Lightning wallet can pay it. This is how an agent charges a customer, another agent, or its own operator from an outside wallet.
• An operator funding the agent with fund_agent. This moves sats from the operator's balance to a specific agent sub-wallet inside the platform. No invoice is involved.

Use the first when the money comes from outside. Use the second when you are budgeting your own fleet of agents. Mixing them up is the most common design mistake: an agent that "receives" from its own operator through a full invoice round trip is doing extra work for nothing.

Why a separate sub-wallet per agent helps

With create_agent an operator can create several agents, each with its own balance and optional budget. For receiving, that means income can be separated by purpose. A research agent that sells summaries and a trading helper that collects tips do not share one pot, so get_transactions for each one reads as its own ledger. You can see at a glance which agent earned what.

Step 1: create the invoice

The call is create_invoice (also accepted as receive). It takes two fields:

• amount_sats: a whole number of sats. The minimum is 1 sat and the maximum is 10,000,000 sats per invoice. Anything outside that range returns an error instead of an invoice.
• memo: optional free text describing the payment.

What comes back

A successful call returns the fields an agent needs to finish the job:

• invoice: the BOLT11 payment request string to give to the payer.
• payment_hash: the identifier you use to check status later. Store it next to your own order or task ID.
• amount_sats: echoed back so you can confirm what you asked for.
• expires_in and expires_at: invoices live for one hour, and expires_at is an ISO 8601 timestamp.

Memo handling you should know about

The memo is cleaned before it goes into the invoice. Only letters, digits, spaces, hyphens, underscores, and periods survive, and the platform prefixes the text with the agent's ID, for example "Agent #123:" followed by your memo. If you send no memo, a default description is used. Practical consequence: do not rely on punctuation, emoji, or symbols in the memo to carry meaning. Put your real reference in your own database, keyed by payment_hash.

Step 2: verify the payment

Verification is a separate call, get_invoice_status, and it takes the payment_hash from step 1. The same lookup is also available under the names check_invoice and check_deposit.

Polling versus webhooks

An agent can poll get_invoice_status on a timer. That works, but it burns calls waiting. When you create an invoice and no webhook is registered, the response includes a tip pointing you to webhooks. The better pattern for anything long-running is to register a webhook for the invoice_paid event, so your service is told when the payment lands instead of asking repeatedly.

A sensible agent loop looks like this:

1. Call create_invoice and store payment_hash, the order it belongs to, and expires_at.
2. Send the invoice string to the payer through whatever channel the agent already has.
3. Wait for the invoice_paid webhook, or poll get_invoice_status at a modest interval until the expiry time.
4. When the status is settled, release the goods or the answer.
5. If expires_at passes with no settlement, discard the invoice and issue a new one if the customer returns.

Settlement is credited exactly once

When a payment is detected, the platform marks the deposit settled and credits the balance in one guarded step. The update only applies if the invoice was still pending, so two overlapping checks cannot credit the same invoice twice. A settled check returns the status, the amount_sats, and the new_balance. If you call status again on an invoice that already settled, you get the same settled answer back rather than a second credit. That makes the call safe to repeat, which is exactly what you want from an agent that may retry after a timeout.

Step 3: confirm the money with get_transactions

Verification of a single invoice answers "did this one arrive". get_transactions answers the wider question: what is this agent's ledger? Each credit from a settled invoice shows up there, so you can reconcile your own records against the platform's.

A reconciliation habit worth adopting

Once a day, or after any batch of work, have the agent list its transactions and compare them to the payment_hash values it stored. A hash you stored that never shows as settled is an unpaid invoice. A credit you do not recognize is worth investigating before you spend it. Small fleets get away without this. Anything handling real customer money should not.

A worked example

Say an agent sells short research briefs. A customer asks for one. The agent calls create_invoice for the agreed amount with a memo such as "market brief", stores the returned payment_hash against the customer's request, and sends the invoice string back in chat. The customer pays from any Lightning wallet. A minute later the webhook fires, the agent calls get_invoice_status, sees settled with the new balance, and delivers the brief. At the end of the day the operator runs get_transactions, matches each credit to a stored hash, and sweeps the balance out. Every step is a single tool call, and none of them requires the agent to understand channels, liquidity, or routing.

What an agent can do with the sats it received

Receiving is rarely the end of the loop. The same sub-wallet that collects payments can also spend them, which is where this connects to the rest of the toolset.

Send onward with Lightning addresses and keysend

pay_lightning_address pays a name@domain address, which is the easiest way to forward a share of earnings to a human or another service. keysend pays a node public key directly with no invoice, using a 66-character hex pubkey, an amount, and an optional message. Both are payments, so they sit behind the agent's lock and cooldown checks. If the agent is locked, or recently had its key rotated, the call is refused with a clear error rather than failing silently.

Pull funds back to the operator

The operator can move sats out of an agent with withdraw_from_agent, including a sweep that takes the whole balance. A tidy pattern is to let agents collect income and have the operator sweep on a schedule, so no agent sits on more value than its job needs. For limits that cap what an agent can spend, read our guide to spending limits for an AI agent wallet.

Wiring it up in practice

Through MCP

If your agent runs inside an MCP client, the receive tools are exposed like any other. Our walkthrough on connecting Claude to a Bitcoin Lightning wallet over MCP shows the setup, after which "create a 2,000 sat invoice for this report" becomes a tool call the model makes itself. If you are going the other direction and charging for your own tools, see building Lightning-paid MCP servers.

Through the API

For direct integration, the AI agent docs list every action and its parameters, and the builder hub collects the SDK, examples, and quickstarts. Keep your operator key on the server side. The agent-facing calls should run with the least access they need.

Common mistakes

• Reusing one invoice for two customers. An invoice is one payment. Create one per order and key it by payment_hash.
• Ignoring expiry. A one-hour life is plenty for a prompt payer and useless for someone who returns tomorrow. Do not email a stale invoice.
• Trusting the payer's claim. "I paid" is not settlement. Only a settled status from get_invoice_status counts.
• Putting secrets in the memo. The memo is part of the invoice string you hand to a third party.

Spend what you earn

Using the same balance elsewhere

Sats an agent collects are ordinary balance, so they can feed anything else on the platform. If you want to see what a funded balance can do, the earn surfaces are a low-friction place to start, multiplayer poker is sat-denominated from the first hand, and prediction markets let you put a view on an outcome with the same balance. Builders can also read the builder hub to see how agents and apps plug in.