Boltwall

• Name: Boltwall
• URL: https://github.com/Tierion/boltwall
• Category: Lightning paywall middleware / LSAT implementation / paid-API authentication infrastructure
• Tags: bitcoin-ecosystem
• Summary: Boltwall is LSAT/L402-flavored middleware that turns Lightning invoices into paid API access. The note is useful because it shows the implementation surface clearly — 402 challenges, macaroons, caveats, and HODL-invoice handling — not because it is the protocol. Keep it as a concrete middleware specimen, not the standard.
• 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 upward comparison points: l402 and x402.

Control surface

• The leverage sits in middleware defaults: which routes get paywalled, how caveats are enforced, what invoice backend is trusted, and whether HODL-invoice flows are allowed.

• Useful operator glue, but still just a middleware slice under stronger paid-request standards.

• Keep the note pointed upward toward L402 and the broader 402-payment family.

• Last reviewed: 2026-06-04 UTC