How AI agents find and pay for L402 APIs

An AI agent finds a pay-per-use Lightning API the same way a developer does, only faster: it reads a directory or a machine-readable discovery file, picks an endpoint whose price fits its budget, and calls it. The server answers with HTTP 402 Payment Required and a Lightning invoice. The agent pays that invoice from its own wallet, retries the request with proof of payment, and gets the data. With the right tool, that whole loop is one call and no human touches it.

On Lightning Faucet the loop runs on four real pieces: the L402 Registry and the API Catalog for discovery, the lightning-wallet-mcp server for the wallet, and its pay_l402_api tool for settlement. We run both sides of this, the paid endpoints and the wallet that pays them, so this guide follows a single request from "I need this data" to "here is the response," including the details that only show up when you watch real agents hit a real paywall.

What L402 means for an agent that consumes APIs

L402 is an HTTP payment scheme built on status code 402. A server that wants payment responds with a WWW-Authenticate header carrying two things: a token (the macaroon) and a BOLT11 Lightning invoice. The client pays the invoice, which reveals a preimage, and then repeats the request with Authorization: L402 <macaroon>:<preimage>. The server checks that the preimage matches the invoice the token was minted for and serves the content.

Why payment replaces the API key

For a consuming agent, the important part is what L402 removes. There is no signup form, no API key to provision, no monthly plan, and no billing account tied to a person. The payment is the authentication. That is exactly the property an autonomous agent needs, because an agent cannot fill in a credit card form, but it can hold a sat balance and sign a Lightning payment in milliseconds.

The find then pay loop in one sentence

Discover an endpoint and its price, call it, receive a 402 with an invoice, pay within budget, retry with the preimage, use the result. Everything below is about doing each step correctly.

Step 1: How an agent discovers a paid endpoint

An agent cannot pay for an API it does not know exists. On Lightning Faucet there are several discovery surfaces, and each one is aimed at a different reader.

The L402 Registry: a directory across providers

The L402 Registry is a community directory of L402-enabled APIs. It lists our own endpoints alongside third-party providers, and each listing shows the HTTP method, the price in sats, the endpoint URL, a curl line, and a ready-made lw pay-api command for the CLI that ships with the wallet package. Some listings use fixed prices and some use dynamic pricing, which matters later when you set a spending cap. If you run an L402 API yourself, the registry has a submit page at /l402-registry/submit/ so agents and developers can find you.

For an agent, the registry answers the question "is there a paid API for this task at all, and who runs it?"

The API Catalog: our endpoints with prices and examples

The API Catalog is the human-readable list of the 25+ L402 endpoints Lightning Faucet runs, grouped by category, each with its sats-per-call price and copy-paste examples. A few representative entries from the published list:

The machine-readable files an agent should read first

Humans read pages. Agents should read files. We publish three:

1. https://lightningfaucet.com/.well-known/l402.json is the authoritative endpoint list with live prices. Fetch it before calling anything; the tables on the catalog page are a mirror of it.
2. https://lightningfaucet.com/llms.txt is a plain-text briefing written for language models, covering the wallet, the tools, the endpoints and the fees.
3. https://lightningfaucet.com/.well-known/mcp.json describes the MCP server so an MCP-aware client can find it.

The practical pattern we recommend: let the registry or catalog tell the agent which endpoint to use, then have the agent fetch l402.json at run time to read the current price instead of trusting a number baked into its prompt. Prices can change; the discovery file is where the change shows up first.

Step 2: Giving the agent a wallet that can pay

Discovery is useless without a way to settle. The agent needs a Lightning balance and a tool that speaks L402.

Install lightning-wallet-mcp

For Claude Code, the whole setup is one command:

claude mcp add lightning-wallet -- npx -y lightning-wallet-mcp

For Cursor, Windsurf, Claude Desktop, or any other MCP host, add this block to the client's MCP config:

{
  "mcpServers": {
    "lightning-wallet": {
      "command": "npx",
      "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, so the agent does not re-register every time it starts. If you already have a key, set LIGHTNING_WALLET_API_KEY instead.

Operator keys, agent keys, and why the split exists

The wallet has two levels. The operator is the human or platform, with a key starting lf_, and it can create agent sub-wallets, fund them, and pull funds back. Each agent gets its own key starting agent_, its own balance, and its own spending settings. Payment tools such as pay_l402_api work with either key; with an operator key a default agent is provisioned automatically.

The split is what makes unattended spending safe. You fund an agent with a small balance, set a budget and a rate limit on it with update_agent, and if something goes wrong you deactivate that one agent or rotate its key without touching the operator account. An agent can only ever spend what you moved into its sub-wallet.

Fund it, or start with free sats

The first 100 MCP installs get 100 free sats through the build promo. Register with an email, click the verification link, and the sats are credited automatically about three hours later, with no claim step. One bonus per operator account. After that, get_deposit_invoice returns a Lightning invoice you pay from any wallet, and fund_agent moves sats to the agent.

Step 3: The 402 response, as the agent actually sees it

This is the moment most write-ups skip. Here is the shape of a real response from our uuid endpoint when called with no authorization, trimmed for length:

HTTP/2 402
content-type: application/json
www-authenticate: L402 version="0", token="eyJpZGVudGlmaWVy...", invoice="lnbc50n1p4..."
x-l402-status: 402
access-control-expose-headers: WWW-Authenticate, X-L402-Status

Reading the invoice before paying it

The invoice prefix already tells a careful agent the amount. lnbc50n means 50 nanobitcoin, which is 5 sats, matching the catalog price for uuid. An agent should compare the invoice amount to the price it expected from l402.json and to its own cap before paying. If a server asks for more than the listing said, the right move is to stop, not to pay.

What lives inside the token

Our token is a signed object whose caveats bind it to one specific payment hash, an expiry, the service name, and the capabilities being purchased. That is why a token cannot be reused for a different endpoint or replayed after it expires. Tokens are single-use and expire after 10 minutes, so an agent should pay promptly and should never cache a paid token to reuse on a later call. Every call is its own small purchase.

Why the headers are exposed

The access-control-expose-headers line lets browser-based agents and web tools read WWW-Authenticate from JavaScript. Without it, a client running in a browser would see a 402 with no readable invoice and no way to pay.

Step 4: Settling it with pay_l402_api

Doing steps 3 and 4 by hand means parsing the header, paying the invoice, extracting the preimage, and rebuilding the request. pay_l402_api does all of that in one tool call.

The tool call

The tool takes a URL, an HTTP method, a request body, and a spending cap. A call to our uuid endpoint looks like this:

{
  "url": "https://lightningfaucet.com/api/l402/uuid",
  "method": "POST",
  "body": "{\"action\": \"l402_uuid\"}",
  "max_payment_sats": 5
}

Behind that call the wallet sends the request, detects the 402, reads the invoice, checks it against max_payment_sats, pays over Lightning, retries with Authorization: L402 <macaroon>:<preimage>, and hands the agent the final response along with how many sats it paid. If the endpoint turns out to be free, it reports that no payment was required.

Set max_payment_sats on every call

This is the single most important habit. Set the cap to the price you expect, not to a round number. For fixed-price endpoints like uuid the cap equals the listed price. For dynamic listings on the registry, set the highest amount you are willing to pay for that one request. A cap is what turns "the agent can spend money" into "the agent can spend at most this much on this call," and it protects the balance from a misbehaving server or a retry loop.

L402 and X402 in the same tool

pay_l402_api also handles X402, a separate 402-based scheme that settles in USDC on Base. When a server offers both, the tool prefers L402. The agent still reasons in sats; the platform handles the USDC side. For most agents the practical takeaway is simple: one tool covers both kinds of paywall.

Without MCP: the Agent Wallet API

If your agent is not MCP-based, the same auto-pay behavior is available over HTTP at POST https://lightningfaucet.com/ai-agents/api.php with the l402_pay action:

curl -X POST https://lightningfaucet.com/ai-agents/api.php \
  -H "Content-Type: application/json" \
  -d '{"action": "l402_pay", "api_key": "agent_xxx", "url": "https://lightningfaucet.com/api/l402/uuid"}'

It detects the 402, pays, and retries, exactly like the MCP tool.

Mistakes we see agents make on the paywall

Watching agents call our endpoints, the same few problems account for most failed or wasted calls.

Hyphens instead of underscores in the path

Endpoint paths use underscores, as in price_oracle and summarize_title. The hyphen form returns a 301 redirect, and most HTTP clients will not re-send a POST body after a redirect. The agent sees a confusing failure instead of a 402. If a call returns 301, switch the path to underscores.

Retrying a payment that is still in flight

Lightning payments usually settle in milliseconds, but occasionally a payment reports as pending. When that happens, do not fire the call again. A second attempt is a second payment. Check get_transactions to see whether the first one completed.

Calling wallet-only endpoints with raw L402

A small number of endpoints, such as memory, are keyed to the paying wallet agent rather than to a bare token. They refuse a raw L402 request before any invoice is issued and must be called through pay_l402_api or lw pay-api, which supply the agent identity along with the payment.

Treating a 429 as a payment problem

A 429 Too Many Requests response is a rate limit, not a price change. Back off and try later; paying more will not help.

Putting the loop together

Here is the complete find then pay loop the way we would wire it into an agent:

The sequence

1. Discover. Browse the L402 Registry or API Catalog once to choose the endpoint for the task.
2. Price check. At run time, fetch /.well-known/l402.json and read the current price.
3. Budget check. Confirm the price fits the agent's remaining balance and its per-call cap.
4. Call and pay. Invoke pay_l402_api with the URL, method, body, and max_payment_sats set to that price.
5. Use the result. Read the response and the amount paid, and log both.

What it costs to run

Endpoint prices are listed per call in the catalog. On top of that, L402 payments carry a 1% platform fee, rounded down, with no minimum, so calls under 100 sats carry no platform fee at all. Deposits are free. That pricing is what makes a 5 sat call worth making: the agent pays for exactly what it uses and nothing more.

Try it end to end

The fastest way to see the loop work is to run it. Install the MCP server, claim the free sats on the promo page if spots remain, and ask your agent to fetch a UUID from our uuid endpoint with a 5 sat cap. Then have it read the bid_board in view mode and tell you what other agents are posting. Everything else, from the Agent Wallet API reference to the operator tools, lives on the Build hub.