BOLT-11 Invoice Format

What Is the BOLT-11 Invoice Format?

The BOLT-11 invoice format is the original payment request standard for the Lightning Network. Defined in BOLT #11 of the Lightning specification, it encodes everything a sender needs to complete a payment: the recipient's identity, the payment amount, a cryptographic hash that locks the funds, an expiry time, and optional routing hints for reaching private channels.

When you scan a Lightning QR code or paste an invoice string starting with lnbc, you are reading a BOLT-11 invoice. The format uses bech32 encoding (the same scheme used for SegWit addresses) to produce a human-readable, error-detecting string that wallets can parse without ambiguity.

BOLT-11 was introduced alongside the broader BOLT specification suite and has served as the dominant Lightning payment request format since the network launched. While BOLT-12 is gradually replacing it for advanced use cases, BOLT-11 remains the most widely supported invoice format across Lightning wallets and services today.

How It Works

Every BOLT-11 invoice is a single string composed of three parts: a human-readable prefix, a separator, and an encoded data payload. Together, they carry all the information required to route and settle a Lightning payment.

Invoice Structure

A BOLT-11 invoice string has this layout:

┌─────────────────────┬───┬──────────────────────────────┐
│  Human-Readable Part│ 1 │         Data Part             │
│  (HRP)              │sep│                               │
├─────────────────────┼───┼──────────────────────────────┤
│ ln + network + amt  │ 1 │ timestamp + tags + signature  │
└─────────────────────┴───┴──────────────────────────────┘

Example: lnbc2500u1pj9...
         ^^^^^^^^        ← HRP: ln (Lightning) + bc (mainnet) + 2500u (amount)
                 ^       ← separator: "1"
                  ^^^^   ← data part (bech32-encoded)

1. The human-readable part (HRP) starts with ln, followed by a network code (bc for mainnet, tb for testnet, bcrt for regtest), and optionally an amount with a multiplier suffix
2. The separator is always the character 1, following the bech32 standard
3. The data part contains a Unix timestamp, tagged fields carrying payment metadata, a 65-byte ECDSA signature, and a 6-character bech32 checksum

Amount Encoding

The amount in the HRP is denominated in bitcoin with a multiplier suffix to express smaller values:

Omitting the amount creates an open invoice where the sender chooses how much to pay. This is common for donation pages and tip jars.

Tagged Fields

The data part contains tagged fields that carry the payment's metadata. Each field has a 5-bit type tag, a 10-bit length, and a variable data payload. The key fields are:

Every valid BOLT-11 invoice must contain exactly one p (payment hash) field, exactly one s (payment secret) field, and either a d or h description field.

Signature and Key Recovery

The invoice ends with a 65-byte ECDSA signature over the entire HRP and data part. The final byte is a recovery ID (0 through 3) that allows any reader to derive the recipient's public key directly from the signature, without needing the optional n field. This is why the payee public key tag is not required: the signature itself proves who created the invoice and allows the sender to identify the destination node.

Decoding Example

Lightning implementations provide tools to decode BOLT-11 invoices into their component fields:

# Decode a BOLT-11 invoice with lncli
$ lncli decodepayreq lnbc2500u1pj9nr...

{
    "destination": "03e7156ae33b0a208d0744199163177e...",
    "payment_hash": "0001020304050607080910111213141516...",
    "num_satoshis": "250000",
    "timestamp": "1685000000",
    "expiry": "3600",
    "description": "Order #1234",
    "cltv_expiry": "18",
    "route_hints": [...],
    "features": { "9": { ... } }
}

Use Cases

Point-of-Sale Payments

The most common use of BOLT-11 invoices is retail payments. A merchant generates a fresh invoice for each transaction, displays it as a QR code, and the customer scans and pays. The invoice's description field typically carries the order reference, and the amount is fixed to the purchase total. Settlement is final within seconds.

Programmatic Payments

Applications use BOLT-11 invoices for machine-to-machine payments. APIs return invoice strings that calling services pay automatically. This pattern powers pay-per-API-call services, metered streaming payments, and hodl invoice escrow flows where settlement is deliberately delayed until conditions are met.

Withdrawal and Refund Flows

When a user requests a withdrawal from a custodial service, they generate a BOLT-11 invoice from their own wallet and submit it. The service pays the invoice, sending funds to the user. The same pattern applies to refunds: the buyer provides an invoice for the refund amount.

Cross-Layer Swaps

BOLT-11 invoices serve as one leg of atomic swaps between on-chain Bitcoin and Lightning. Services like Loop use the payment hash from a BOLT-11 invoice to construct a matching on-chain HTLC, enabling trustless movement of funds between layers.

Risks and Considerations

Single-Use Limitation

Each BOLT-11 invoice contains a unique payment hash. Once paid, the preimage is revealed to every forwarding node along the route. If a second payment uses the same invoice, any of those nodes could intercept it by replaying the preimage. This means recipients must generate a fresh invoice for every transaction, requiring them to be online and running invoice-generation infrastructure.

No Recipient Privacy

A BOLT-11 invoice exposes the recipient's node public key, either explicitly in the n field or recoverable from the signature. Anyone who obtains the invoice string can identify which Lightning node will receive the payment. For merchants and services, this links payment activity to a known public identity. This is one of the primary motivations for BOLT-12, which uses blinded paths to conceal the recipient's node.

Invoice Expiry and User Friction

BOLT-11 invoices expire by default after one hour. If a user generates an invoice but the payer does not act promptly, the invoice becomes invalid and a new one must be created. While the expiry time is configurable, long expiry windows increase the risk of payment hash reuse attacks, and very short windows create friction in asynchronous payment flows.

Route Hint Bloat

Invoices from nodes with only private channels must include route hints so senders can find a path. Each hint encodes a channel ID, node public key, fee parameters, and CLTV delta: 51 bytes per hop. Invoices with multiple route hints can grow quite large, producing dense QR codes that some mobile cameras struggle to scan reliably.

Why BOLT-12 Supersedes BOLT-11

BOLT-12 introduces reusable payment offers (prefixed lno) that address the core limitations of BOLT-11. Instead of encoding a single-use payment hash directly, a BOLT-12 offer acts as a lightweight pointer. The sender contacts the recipient via onion-routed messaging to request a fresh invoice on demand.

For a deeper comparison, see the research article on Lightning invoices: BOLT-11 and BOLT-12 and the BOLT-12 offers deep dive.

BOLT-11 and Spark

Spark is a Layer 2 protocol for Bitcoin that supports both Lightning-compatible payments and native transfers. Applications built on Spark can generate and pay BOLT-11 invoices, giving users access to the full Lightning Network while benefiting from Spark's self-custodial architecture. As the ecosystem transitions toward BOLT-12, Spark's infrastructure supports both formats, allowing developers to adopt newer payment flows without abandoning compatibility with existing Lightning wallets and services.

This glossary entry is for informational purposes only and does not constitute financial or investment advice. Always do your own research before using any protocol or technology.