BOLT11 Decoder Libraries

BOLT11 invoices are bech32-encoded with structured TLV-like tags. Multiple language libraries handle parsing.

JavaScript / TypeScript

bolt11 (npm):

npm install bolt11

const bolt11 = require("bolt11");
const decoded = bolt11.decode("lnbc100u1p...");
// {
//   payeeNodeKey: "...",
//   tagsObject: { payment_hash, description, ... },
//   millisatoshis: "10000000",
//   timeExpireDate: ...
// }

// Encode
const enc = bolt11.encode({
    millisatoshis: "10000000",
    tags: [
        { tagName: "payment_hash", data: "abc..." },
        { tagName: "description", data: "Pay" },
    ],
}, { network: "bitcoin" });

Alternative: light-bolt11-decoder, @atomiqlabs/bolt11.

Maintenance status as of September 2026: npm bolt11 is still frozen at 1.4.1, published 2023-03-22, and light-bolt11-decoder at 3.2.0, published 2024-09-20. Both still decode today's invoices, but neither has a live release line. For new code @atomiqlabs/bolt11 is a maintained fork of bitcoinjs/bolt11 exporting the same decode / encode / sign API, at 1.6.2 (2026-08-14). Whichever you take, pin the version and keep an invoice corpus in your own tests rather than assuming new tag types get handled.

Python

pylnurl-style or bolt11-py:

from bolt11 import decode
decoded = decode("lnbc100u1p...")
print(decoded.amount_msat, decoded.payment_hash)

Rust

lightning-invoice (part of LDK):

// lightning-invoice = "0.34"   // 0.34.1, June 2026
use lightning_invoice::Bolt11Invoice;
let invoice: Bolt11Invoice = "lnbc100u1p...".parse()?;
println!("{:?}", invoice.amount_milli_satoshis());

Go

github.com/lightningnetwork/lnd/zpay32 — the BOLT11 codec that ships inside LND — is the canonical Go implementation. There is no lightninglabs/lightning-invoice module and no btcsuite BOLT11 package (neither exists as of September 2026):

import (
    "github.com/btcsuite/btcd/chaincfg"
    "github.com/lightningnetwork/lnd/zpay32"
)

invoice, err := zpay32.Decode("lnbc100u1p...", &chaincfg.MainNetParams)
// invoice.MilliSat, invoice.PaymentHash, invoice.Destination, invoice.Timestamp

Decoding is network-parameterised: the chaincfg.Params must match the invoice HRP or Decode fails. Encoding is a method on *Invoice that takes a signer — invoice.Encode(signer) with a zpay32.MessageSigner.

BOLT12 decoder

For BOLT12 offers, separate libraries (newer):

lightning-offers (Rust / LDK).
lib-bolt12 (Python).
Limited JS/TS support so far.

Common bugs

Network mismatch (testnet vs mainnet decoding).
Padding handling in bech32 — some libs strict, others lenient.
Min-final-CLTV-expiry default if not in invoice.

bitcoin-libraries-bolt11