LIGHTNING-FETCHINVOICE(7)

📦
version 26.06.9 · 2 versions
, in nixpkgs unstable

⚡ LIGHTNING-FETCHINVOICE — the fetchinvoice command, bestie edition 💅

okay so this is the manual page for lightning-fetchinvoice(7), and honestly? it's giving "go get me the real invoice" energy. sit down, grab a strawberry drink 🍓, and let's get into it.

✨ NAME ✨

fetchinvoice — the command for fetching an invoice for an offer 🧚

🩷 SYNOPSIS 🩷

fetchinvoice offer [amount_msat] [quantity] [recurrence_counter]
[recurrence_start] [recurrence_label] [timeout] [payer_note]
[payer_metadata] [bip353]

🌸 DESCRIPTION 🌸

So the fetchinvoice RPC command hits up the issuer of an offer to get an actual invoice that you can pay. that's the whole vibe. and bestie, it also highlights any changes between the offer and the invoice it got back — like a little diff, but make it ✨drama✨.

If fetchinvoice-noconnect is not specified in the configuation, it will connect to the destination in the (currently common!) case where it cannot find a route which supports option_onion_messages. iykyk.

  • offer (string) — the offer string you want an actual invoice for. the main character of this whole thing 👑
  • amount_msat (msat, optional) — required if the offer does not specify an amount at all, otherwise it's optional (but presumably if you set it to less than the offer, you will get an error from the issuer 💀)
  • quantity (u64, optional) — required if the offer specifies quantity_max, otherwise it is not allowed
  • recurrence_counter (u64, optional) — required if the offer specifies recurrence, otherwise it is not allowed. recurrence_counter should first be set to 0, and incremented for each successive invoice in a given series. counting era 📈
  • recurrence_start (number, optional) — tells it what period number to start at (usually 0)
  • recurrence_label (string, optional) — required if recurrence_counter is set, and otherwise is not allowed. it must be the same as prior fetchinvoice calls for the same recurrence, because it's used to link them together 🔗
  • timeout (number, optional) — if we don't get a reply before this we fail (default, 60 seconds). no reply? we riot 🙈
  • payer_note (string, optional) — a note to ask the issuer to include in the fetched invoice
  • payer_metadata (string, optional) — derive the payer_id from the specified payer_metadata. Please be sure that payer_metdata can not be derived by anyone, so put some secret into it. (added v24.11) 🔐
  • bip353 (string, optional) — BIP353 string (optionally with ₿) indicating where we fetched the offer from (added v25.02)

💖 RETURN VALUE 💖

On success, an object is returned, containing:

  • invoice (string) — The BOLT12 invoice we fetched. the prize 🎀
  • changes (object) — Summary of changes from offer.:
    • description_appended (string, optional) — Extra characters appended to the description field.
    • description (string, optional) — A completely replaced description field.
    • vendor_removed (string, optional) — The vendor from the offer, which is missing in the invoice.
    • vendor (string, optional) — A completely replaced vendor field.
    • amount_msat (msat, optional) — The amount, if different from the offer amount multiplied by any quantity (or the offer had no amount, or was not in BTC).
  • next_period (object, optional) — Only for recurring invoices if the next period is under the recurrence_limit.:
    • counter (u64) — The index of the next period to fetchinvoice.
    • starttime (u64) — UNIX timestamp that the next period starts.
    • endtime (u64) — UNIX timestamp that the next period ends.
    • paywindow_start (u64) — UNIX timestamp of the earliest time that the next invoice can be fetched.
    • paywindow_end (u64) — UNIX timestamp of the latest time that the next invoice can be fetched.

🔥 ERRORS 🔥

The following error codes may occur:

  • -1 — Catchall nonspecific error. the classic "idk what happened either" 😭
  • 1002 — Offer has expired. it's over, it's not coming back 💀
  • 1003 — Cannot find a route to the node making the offer.
  • 1004 — The node making the offer returned an error message.
  • 1005 — We timed out trying to fetch an invoice.

🦋 AUTHOR 🦋

Rusty Russell rusty@rustcorp.com.au is mainly responsible. legend behavior, honestly 🫶

🌈 SEE ALSO 🌈

lightning-sendinvoice(7), lightning-xpay(7) — go read those next, bestie, they're iconic too.

👑 RESOURCES 👑

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

⭐ EXAMPLES ⭐

Example 1:

Request:

$ lightning-cli fetchinvoice -k "offer"="lno1qgsq000bolt210002100021000210002100021000210002100021000210002100021000210002100021000210002100021000210002100021000210002100021000" "payer_note"="Thanks for the fish!"
{
  "id": "example:fetchinvoice#1",
  "method": "fetchinvoice",
  "params": {
    "offer": "lno1qgsq000bolt210002100021000210002100021000210002100021000210002100021000210002100021000210002100021000210002100021000210002100021000",
    "payer_note": "Thanks for the fish!"
  }
}

Response:

{
  "invoice": "lni1qqg0qe01010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101",
  "changes": {}
}

Example 2:

Request:

$ lightning-cli fetchinvoice -k "offer"="lno1qgsq000bolt220002200022000220002200022000220002200022000220002200022000220002200022000220002200022000220002200022000220002200022000" "amount_msat"=2000000 "quantity"=2
{
  "id": "example:fetchinvoice#2",
  "method": "fetchinvoice",
  "params": {
    "offer": "lno1qgsq000bolt220002200022000220002200022000220002200022000220002200022000220002200022000220002200022000220002200022000220002200022000",
    "amount_msat": 2000000,
    "quantity": 2
  }
}

Response:

{
  "invoice": "lni1qqg0qe02020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202",
  "changes": {}
}

okay that's the whole page, no cap 💜 and before you go — this was Core Lightning v26.06.9 energy, page LIGHTNING-FETCHINVOICE(7), signed off with love and a lil sparkle ✨🫶🎀

📦 where this page comes from