Custodial Lightning's Quiet L402 Compatibility Problem
Notes from production: when the preimage doesn't come back, and what it means for Lightning at scale.
L402 is one of the most elegant pieces of protocol design Lightning has produced. It takes the web's HTTP 402 "Payment Required" status — sitting unused since the spec was drafted in 1996 — and finally gives it a real payment rail. An API returns 402 with a Lightning invoice. The client pays. The client presents the preimage as proof. The server verifies and grants access. No accounts. No API keys. No minimum charges. No middlemen.
It's how AI agents will pay for things.
Building on top of L402 in production, though, we've run into something that doesn't show up in the spec, the wallet docs, or any of the published implementation notes. It's worth talking about because it shapes how L402 will work — or not work — as agent commerce scales.
How the proof chain is supposed to work
L402's proof-of-payment is a beautiful piece of cryptography. Here's the chain:
- The merchant generates a random 32-byte secret — the preimage.
- The merchant computes
SHA256(preimage)— the payment hash — and embeds it in a BOLT11 Lightning invoice. - The buyer's wallet pays the invoice. Funds move across the Lightning Network as a series of HTLCs (Hash Time-Locked Contracts), each conditioned on that same payment hash.
- When the HTLC reaches the merchant's node, they release the preimage to claim the funds. The preimage propagates backward through the route. Every hop uses it to settle the HTLC and pass it upstream, until it reaches the buyer's wallet.
- The buyer now holds the preimage. They present it as
Authorization: L402 <macaroon>:<preimage>on their next request. - The server verifies
SHA256(preimage) == payment_hashand grants access.
That's it. No trusted third party. No oracle. The cryptographic chain is the protocol. If the buyer holds a value whose hash matches what the server committed to, the buyer paid for it. Period.
It's gorgeous on paper. And it works perfectly when both the buyer's wallet and the merchant's settlement layer participate in real Lightning routing.
What we observed in production
We've seen Lightning payments that succeed — the merchant gets paid, the funds land in their account, our backend confirms via webhook — but the buyer never receives a preimage. The chain breaks silently.
The merchant has the funds. The buyer has the receipt. But the buyer can't prove they paid in the way L402 requires, because the value that should have flowed backward through the route was never generated. There was no route. The payment didn't take a Lightning hop at all.
It happens when both the payer's wallet and the merchant's settlement layer are hosted by the same custodian.
Why custodial Lightning routes around its own protocol
Custodial Lightning services — the wallets and processors that hold customer funds and operate the underlying Lightning nodes on their users' behalf — have a natural optimization. When a payer on platform X sends money to a recipient on platform X, the platform doesn't need to construct an HTLC, find a route, lock liquidity, or pay routing fees. It can just credit one internal account and debit another. A database write instead of a Lightning hop.
This is faster. It's cheaper. It's more reliable. It avoids HTLC failure modes. From the custodian's perspective, it's the right move. Most custodial Lightning services do it, with varying degrees of explicitness.
It's also completely invisible to L402. The buyer's wallet records "payment sent." The merchant's account shows the funds. Neither side sees a preimage because no preimage was used. There was no HTLC to settle, so nothing flowed backward through any route. The cryptographic chain L402 depends on simply doesn't form.
This isn't malicious behavior. The custodians aren't doing anything wrong. They're optimizing for the experience of their users — speed, cost, reliability — exactly as they should. The L402 proof-of-payment chain is collateral damage of a design decision that makes sense in every other respect.
The silent fallback
The headline issue isn't that the preimage is missing. It's what the protocol falls back toward when it is.
L402's defining property — the one that makes it interesting as agent infrastructure at all — is stateless, vendor-independent verification. The server doesn't call the wallet. It doesn't maintain OAuth sessions, webhook subscriptions, or vendor-specific lookup APIs. It hashes the bytes the client presents and either grants access or doesn't. No third party stands between the proof and the verification. That's the whole point of 402 in 2026.
When the preimage doesn't come back, the protocol doesn't fail loudly. It leans, quietly, back toward everything L402 was supposed to replace. To know whether the payment really happened, the server now has to ask someone — the custodian, via a webhook callback or a payment-status API. That's a trusted intermediary in the path. That's vendor lock-in. That's the exact stack of accounts, keys, and middlemen 402 was designed to clear off the web. The cryptography didn't fail; the architecture quietly regressed.
Why this matters more as the ecosystem grows
The percentage of Lightning users on custodial wallets is large and growing. A handful of custodians account for the vast majority of retail Lightning users. Self-custody Lightning — running your own LND node, managing your own channels — remains a smaller minority by user count.
This means that as L402 adoption grows, so does the compatibility surface. The more Lightning activity concentrates inside large custodial platforms, the more often buyer and merchant will sit on the same provider, and the more often L402's proof chain risks being silently bypassed by internal settlement optimizations.
That matters even more as custodial Lightning explicitly targets agent commerce. Several major Lightning vendors have publicly committed to AI agent payments as a priority category. Their motivation is right. The compatibility gap with L402 is the part that now needs ecosystem attention.
Three potential paths forward
There's no single fix. There are three plausible paths, and they're not mutually exclusive.
1. BOLT12 with blinded paths. BOLT12 is the next-generation Lightning offer/invoice protocol, with first-class support for blinded paths — routing where the destination is hidden from the payer's wallet. If the destination pubkey is hidden, the custodian can't recognize "this is one of our nodes" and can't optimize the payment into an internal transfer. They'd be forced to route over real Lightning. This is the cleanest protocol-level fix. The cost is BOLT12's still-thin deployment. Most major wallets don't support it yet for either send or receive.
2. An opt-in real-routing flag from custodial vendors. A custodian could expose, at invoice creation, a flag like disableInternalRouting: true that promises any payment against this invoice will route over real Lightning regardless of source. The merchant signals "I need the preimage chain to complete" and the custodian honors it. This is lightweight — a small API addition on the custodian's side. It depends on vendor cooperation, but it's the kind of feature that can be priced (custodians lose some routing-fee savings, so let them charge for it) and gated. For L402-sized payments today, the cost to the custodian is essentially zero, so the ask is genuinely small.
3. L402 spec evolution. It may be time to consider whether L402's proof-of-payment can be expressed in more than one way. The preimage is elegant when real Lightning routing happens, but it's not the only possible proof. A server-signed receipt the buyer can present, backed by the merchant's signature on the invoice + payment confirmation, would work even when the underlying payment never produced a preimage. This is a bigger lift. It requires careful spec work to avoid breaking the trust model. But it would future-proof L402 against custodial optimization without requiring vendor cooperation.
These three paths aren't competitors. (1) is the protocol-purist answer. (2) is the pragmatic-near-term answer. (3) is the future-proofing answer. The healthiest outcome is probably a mix.
What I tried
In May 2026, I opened a pull request to lightninglabs/L402 proposing a narrower version of path (3) — not a new proof type, but an explicit normative requirement on the existing one. A new Section 7 in the protocol specification with three bullets:
- Wallets and payment processors MUST surface the preimage to the client for any settled invoice, regardless of whether settlement was HTLC-routed or handled via internal accounting on a single custodial service.
- Omitting the preimage on the payment-confirmation response for an internally-settled invoice SHOULD be considered non-compliant for L402 purposes.
- Wallets and payment processors MUST NOT release the preimage prior to invoice settlement.
The first bullet closes the compatibility gap described above. The third preserves the implicit "preimage possession ⟹ payment occurred" property that L402's stateless H == sha256(r) check depends on. None of it requires new cryptography, new spec primitives, or a fork — just an explicit statement that "settled" means "settled, with the preimage surfaced to the client."
The pace at which agent commerce is moving does not match the pace at which the spec layer is moving, and that is a fact about the situation, not a complaint. Builders ship around gaps, and they have before. This piece is here so the next builder running into the same wall doesn't have to spend a week figuring out why the preimage didn't come back.
Why this is worth attention now
The proof chain works cleanly when the buyer runs their own node. It works cleanly when the buyer and merchant use different custodians and the payment actually routes. It does not work reliably today when both sides sit on the same custodian — which, given the concentration of Lightning users on a handful of platforms, is an increasingly common case.
That's not a reason to slow down. L402 still solves the hard part. Agents paying for resources autonomously, APIs monetized without signup flows, machine-speed programmatic commerce — all of that is real and shipping. The preimage gap is a known shape now, with known mitigations.
If you're building an L402 service: ship the client-side recovery (cache any returned preimage by payment hash before retrying the authenticated request; if the wallet replies "already paid," look it up locally) and the server-side fallback (recognize already-settled invoices on legitimate retry and re-issue the macaroon/preimage pair). Document what you observe so the next builder doesn't have to rediscover it.
If you're building a wallet or running a custodial Lightning service: document your preimage behavior on incoming, outgoing, and same-platform payments. Vendor-by-vendor opacity is the slowest path to ecosystem-wide reliability. The custodians that are explicit about this will be the ones agent builders trust to build against. And if you want a hand stress-testing your preimage behavior on internal vs. routed settlement before you publish anything — reach out directly at support@lightningenable.com. We run a working L402 deployment in production and can tell you exactly what we see end-to-end, fast and without hedging.
If you're an agent builder: this gap is real today and will get smaller over time. It is not a reason to wait. Build, surface what you find, and the ecosystem will close the gap — while the spec layer catches up.
Lightning Enable is .NET infrastructure for L402-based agent commerce — open-source clients, an MCP server, and merchant integration tooling. We ship the client-side preimage recovery and server-side fallback that make L402 work today, including against the gap described above. lightningenable.com