LIGHTNING-INVOICE(7)

📦

version 26.06.9 · 2 versions

26.06.9 · nixpkgs unstable (latest)
26.04.1 · nixos 26.05

💖 LIGHTNING-INVOICE(7) — invoice, aka the "pls pay me" command 🎀

okay so before we even start: this is the lightning-invoice(7) manual page, and it's lowkey the most main-character command in the whole RPC lineup. it's how you ask the entire lightning network for money, and it's genuinely not that deep once you get the vibe. let's go 💅

✨ NAME ✨

invoice — the command for accepting payments. yeah. that's it. that's the whole thing. it makes invoices so people can give you sats 🫶

🌸 SYNOPSIS 🌸

invoice amount_msat label description [expiry] [fallbacks] [preimage]
[exposeprivatechannels] [cltv] [deschashonly]

🦋 DESCRIPTION 🦋

so the invoice RPC command does one iconic thing: it creates the expectation of a payment of a given amount of milli-satoshi. basically it slides back a unique token that another lightning daemon can use to pay this invoice. and if there happens to be an incoming channel with the capacity to pay it, that token also carries a route hint description for it. it's giving "here's the map, bestie" 🗺️✨

amount_msat (msat_or_any) — the string any, which creates an invoice that can be paid with any amount (chaotic, love that for you). otherwise it's a positive value in millisatoshi precision. and it's flexible, so it can be:
- a whole number
- a whole number ending in msat or sat
- a number with three decimal places ending in sat
- a number with 1 to 11 decimal places ending in btc
label (one of) — a unique string or number (which is treated as a string, so 01 is different from 1 — yes, fr fr, they're not the same). it is never revealed to other nodes on the lightning network, but it can be used to query the status of this invoice. it's your private little handle for it 🙈
- (string)
- (integer)
description (string) — a short description of the purpose of payment, e.g. 1 cup of coffee. this value is encoded into the BOLT11 invoice and is viewable by any node you send this invoice to (unless deschashonly is true as described below). it must be UTF-8, and cannot use \u JSON escape codes. so no sneaky escape-code nonsense 🚫
expiry (u64, optional) — the time the invoice is valid for, in seconds. if no value is provided the default of 604800 (1 week) is used. one whole week to pay up, no pressure 💀
fallbacks (array of strings, optional) — one or more fallback addresses to include in the invoice, in order from most-preferred to least. but heads up: note that these arrays are not currently tracked to fulfill the invoice. so they're decorative, essentially 🎀
- (string, optional)
preimage (hex, optional) — a 64-digit hex string to be used as the payment preimage for the created invoice. by default, if unspecified, lightningd will generate a secure pseudorandom preimage seeded from an appropriate entropy source on your system. IMPORTANT: if you specify the preimage, you are responsible to ensure appropriate care for generating using a secure pseudorandom generator seeded with sufficient entropy, and keeping the preimage secret. this parameter is an advanced feature intended for use with cutting-edge cryptographic protocols and should not be used unless explicitly needed. > seriously bestie, this is the "do not touch unless you know exactly what you're doing" zone. if you mess up the entropy or leak the preimage, that's on you, not on me 😭
exposeprivatechannels (one of, optional) — if specified, it overrides the default route hint logic, which will use unpublished channels only if there are no published channels. pick your fighter:
- (boolean): if True, unpublished channels are always considered as a route hint candidate; if False, never.
- (array of short_channel_ids): array of short channel ids (or a remote alias) — only those specific channels will be considered candidates, even if they are public or dead-ends.
- (short_channel_id, optional)
- (short_channel_id): if it is a short channel id (e.g. 1x1x3), only this specific channel will be considered candidate, even if it is public or dead-end.
cltv (u32, optional) — if specified, sets the min_final_cltv_expiry for the invoice. otherwise, it's set to the parameter cltv-final. ⏳
deschashonly (boolean, optional) — if True, then the bolt11 returned contains a hash of the description, rather than the description itself. this allows much longer descriptions, but they must be communicated via some other mechanism. the default is False. iykyk 🔥

👑 RETURN VALUE 👑

on success, an object is returned, containing:

bolt11 (string) — the bolt11 string. this is the actual invoice, the thing you send people 👑
payment_hash (hash) — the hash of the payment_preimage which will prove payment.
payment_secret (secret) — the payment_secret to place in the onion.
expires_at (u64) — UNIX timestamp of when the invoice expires.
created_index (u64) — 1-based index indicating the order this invoice was created in. (added v23.08 ✨)

the following warnings may also be returned:

warning_capacity — even using all possible channels, there's not enough incoming capacity to pay this invoice. 😭
warning_offline — there would be enough incoming capacity, but some channels are offline, so there isn't.
warning_deadends — there would be enough incoming capacity, but some channels are dead-ends (no other public channels from those peers), so there isn't.
warning_private_unused — there would be enough incoming capacity, but some channels are unannounced and exposeprivatechannels is false, so there isn't.
warning_mpp — there is sufficient capacity, but not in a single channel, so the payer will have to use multi-part payments.

💀 ERRORS 💀

on failure, an error is returned and no invoice is created. and this part matters: if the lightning process fails before responding, the caller should use lightning-listinvoices(7) to query whether this invoice was created or not. don't just assume it didn't happen 🙈

the following error codes may occur:

-1 — catchall nonspecific error. the "something happened but honestly who knows" of error codes.
900 — an invoice with the given label already exists.
901 — an invoice with the given preimage already exists.
902 — none of the specified exposeprivatechannels were usable.

🧚 AUTHOR 🧚

Rusty Russell rusty@rustcorp.com.au is mainly responsible. thank you king 🫶

⭐ RESOURCES ⭐

main web site: https://github.com/ElementsProject/lightning

🍓 EXAMPLES 🍓

Example 1:

request:

$ lightning-cli invoice -k "amount_msat"=10000 "label"="lbl_l31" "description"="Invoice description l31"

{
  "id": "example:invoice#1",
  "method": "invoice",
  "params": {
    "amount_msat": 10000,
    "label": "lbl_l31",
    "description": "Invoice description l31"
  }
}

response:

{
  "payment_hash": "paymenthashinvl0310031003100310031003100310031003100310031003100",
  "expires_at": 1739000000,
  "bolt11": "lnbcrt100n1pnt2bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000",
  "payment_secret": "paymentsecretinvl00310003100031000310003100031000310003100031000",
  "created_index": 2
}

Example 2: