Boltwall

• Name: Boltwall
• URL: https://github.com/Tierion/boltwall
• Category: seller-side Lightning paywall middleware / LSAT-L402 implementation / paid-route gate
• Tags: bitcoin-ecosystem
• Summary: Boltwall is seller-side Lightning paywall middleware. It takes a protected route, returns a 402, checks a macaroon-plus-preimage credential on the retry, and can treat held invoices as valid paid state. Useful implementation specimen, not the standard or the broad operator stack.
• What it does:
  • Adds a paywall/auth gate to server routes with a single middleware call such as app.use(boltwall())
  • Returns 402 Payment Required plus a WWW-Authenticate LSAT challenge when an unpaid client requests a protected route
  • Verifies paid access by checking a macaroon-plus-preimage credential presented in the Authorization: LSAT ... header
  • Supports configurable caveats including time-limited access, origin/IP restriction, custom invoice descriptions, and minimum invoice amounts
  • Exposes documented example endpoints for node info, protected resources, invoice creation, and invoice-status lookup
  • Includes HODL-invoice support so a held invoice can represent valid paid state for single-use or conditionally released access flows
  • Connects to LND directly or, per the docs, can alternatively use OpenNode for payment handling
• Key claims:
  • The README and docs say Boltwall lets a developer charge for API access without user accounts, API keys, credit cards, or stored user data, which is the clearest sign that it is positioned as payment-native auth middleware rather than conventional identity software
  • The same materials repeatedly emphasize that a paywall can be added with one line, app.use(boltwall()), which shows the product is packaged as drop-in route middleware instead of a bespoke payments backend
  • The docs describe an LSAT flow where a protected request receives 402 Payment Required, the client pays the invoice, and then replays the request with an Authorization header containing the macaroon and preimage
  • The docs say Boltwall ships prebuilt caveat configs for time-based access and origin/IP restriction, and they give an example where access lasts one second per satoshi paid unless a custom rate is supplied
  • The docs also say Boltwall supports HODL invoices and treats a held invoice as paid for authorization purposes, which materially distinguishes it from a simple invoice-paywall wrapper
  • Tierion’s LSAT explainer says Boltwall predated but later migrated toward LSAT compatibility in collaboration with Lightning Labs and that Tierion used the construction for machine-to-machine payments in Chainpoint
• Whitepaper: No canonical standalone Boltwall whitepaper or litepaper surfaced in this pass. The clearest current source of truth was the canonical repository README, the official GitHub Pages docs, and Tierion’s LSAT explainer; see ../whitepapers/boltwall-primary-sources-2026-05-03.md.
• Sources:
  • https://github.com/Tierion/boltwall
  • https://raw.githubusercontent.com/Tierion/boltwall/master/README.md
  • https://tierion.github.io/boltwall/
  • https://blog.tierion.com/lsats-authentication-using-bitcoin-lightning-payments/

Internal linkages

• Best structural reads: l402 and lightning-agent-tools.

Control surface

• The leverage sits in which routes get paywalled, how macaroons and caveats are scoped, what invoice backend is trusted, whether HODL invoices count as paid state, and how long access survives after settlement.

• That is real seller-side control, but it is still a narrow middleware slice under the stronger Lightning paid-request rail and the broader operator wrappers built around it.

• Last reviewed: 2026-06-14 UTC