LIGHTNING-INVOICEREQUEST(7)

📦
version 26.06.9 · 2 versions
, in nixpkgs unstable

🎀 LIGHTNING-INVOICEREQUEST(7) 🎀

okay bestie, so this is the manual page for lightning-invoicerequest — yes the whole thing, section 7 and everything. welcome to the invoicerequest era, it's giving ✨formal invitation✨ vibes.

💌 NAME 💌

invoicerequest — the command for offering payments. like, you're putting it out into the universe. manifesting that bag. 💸

🌸 SYNOPSIS 🌸

invoicerequest amount description [issuer] [label] [absolute_expiry]
[single_use]

that's it. that's the whole recipe. six little slots, one big slay. 🫶

✨ DESCRIPTION ✨

ngl this command is new new — it was added in v22.11, so if you're on some ancient node bestie, it's not gonna be there, sorry 😭.

so what does the invoicerequest RPC command actually DO? it creates an invoice_request to send payments, and the way it works is lowkey iconic: it automatically enables the processing of an incoming invoice, and payment of it. periodt. then whoever's holding the resulting invoice_request can hit up lightning-sendinvoice(7) to collect their payment. the reader gets paid, you get your thing, everyone eats. 🍓

here's the deets on every single parameter, no gatekeeping:

  • amount (msat) — a positive value in millisatoshi precision. and it's flexible fr fr: it can be a whole number, or a whole number ending in msat or sat, or a number with three decimal places ending in sat, or a number with 1 to 11 decimal places ending in btc. so many lewks, all valid 💅
  • description (string) — a short description of purpose of the payment, e.g. ATM withdrawl. (yes that's exactly how it's spelled in the source, i don't make the rules 🫠.) this value is encoded into the resulting invoice_request and is viewable by anyone you expose it to — so like, don't put your secrets in there bestie, everyone can see it 👀. it must be UTF-8, and it cannot use \u JSON escape codes.
  • issuer (string, optional) — who is issuing it (i.e. you) if appropriate. your name in lights, main character energy 👑
  • label (string, optional) — an internal-use name for the offer, which can be any UTF-8 string. this one's just for you, it's your little tag 🏷️
  • absolute_expiry (u64, optional) — the time the offer is valid until, in seconds since the first day of 1970 UTC. if not set, the invoice_request remains valid (though it can be deactivated by the issuer of course — that's you, you have the power). this is encoded in the invoice_request.
  • single_use (boolean, optional) — indicates that the invoice_request is only valid once. we may attempt multiple payments, but as soon as one is successful no more invoices are accepted (i.e. only one person can take the money 🫰). the default is True. the default is so real.

💖 RETURN VALUE 💖

on success, you get an object back, and here's everything inside it, no crumbs left:

  • invreq_id (hash) — the SHA256 hash of all invoice_request fields less than 160.
  • active (boolean) (always true) — whether the invoice_request is currently active. it just went live bestie 🟢
  • single_use (boolean) — whether the invoice_request will become inactive after we pay an invoice for it.
  • bolt12 (string) — the bolt12 string starting with lnr. she's long, she's iconic, she's a whole string 💫
  • used (boolean) (always false) — whether the invoice_request has already been used. fresh out the box 🌸
  • label (string, optional) — the label provided when creating the invoice_request. only shows up if you gave one 🎀

🚨 ERRORS 🚨

on failure, an error is returned and no invoice_request is created. and here's the slightly scary part: if the lightning process fails before responding, the caller should use lightning-listinvoicerequests(7) to query whether it was created or not. like, go check if the thing exists, don't just assume 😭

  • -1 — catchall nonspecific error. the "idk what happened, it just didn't work" of error codes 💀

🧚 AUTHOR 🧚

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

🔥 SEE ALSO 🔥

(the full trio, use them together, they're a set 💜)

🌈 RESOURCES 🌈

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

go look, it's right there, it's free ⭐

👑 EXAMPLES 👑

Example 1:

Request:

$ lightning-cli invoicerequest -k "amount"=1000000 "description"="Simple test"

{
  "id": "example:invoicerequest#1",
  "method": "invoicerequest",
  "params": {
    "amount": 1000000,
    "description": "Simple test"
  }
}

Response:

{
  "invreq_id": "invreqid01010101010101010101010101010101010101010101010101010101",
  "active": true,
  "single_use": true,
  "bolt12": "lno1qgsq000bolt210002100021000210002100021000210002100021000210002100021000210002100021000210002100021000210002100021000210002100021000",
  "used": false
}

Example 2:

Request:

$ lightning-cli invoicerequest -k "amount"="10000sat" "description"="Requesting for invoice" "issuer"="clightning store"

{
  "id": "example:invoicerequest#2",
  "method": "invoicerequest",
  "params": {
    "amount": "10000sat",
    "description": "Requesting for invoice",
    "issuer": "clightning store"
  }
}

Response:

{
  "invreq_id": "invreqid02020202020202020202020202020202020202020202020202020202",
  "active": true,
  "single_use": true,
  "bolt12": "lno1qgsq000bolt240002400024000240002400024000240002400024000240002400024000240002400024000240002400024000240002400024000240002400024000",
  "used": false
}

look at those juicy bolt12 strings. absolute units. 🔥

and that's the whole page babes 💜 this was Core Lightning v26.06.9, so if you're reading this from some other version, vibe check your node first. mwah, go request some invoices, you got this 🌸🦋🎀

📦 where this page comes from