lightning-fetchinvoice -- Command for fetch an invoice for an
offer
fetchinvoice offer [amount_msat]
[quantity] [recurrence_counter] [recurrence_start]
[recurrence_label] [timeout] [payer_note]
[payer_metadata] [bip353]
The fetchinvoice RPC command contacts the issuer of an
offer to get an actual invoice that can be paid. It highlights any
changes between the offer and the returned invoice.
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.
- offer (string): Offer string to get an actual invoice that can be
paid.
- amount_msat (msat, optional): Required if the offer does not
specify an amount at all, otherwise it is 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.
- recurrence_start (number, optional): Required if the offer
specifies recurrence_base with start_any_period set, otherwise it is not
allowed. It indicates what period number to start at.
- 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, as it is used to link them
together.
- timeout (number, optional): If we don't get a reply before this we
fail (default, 60 seconds).
- payer_note (string, optional): 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)
On success, an object is returned, containing:
- invoice (string): The BOLT12 invoice we fetched.
- 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.
The following error codes may occur:
- -1: Catchall nonspecific error.
- 1002: Offer has expired.
- 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.
lightning-sendinvoice(7), lightning-pay(7)
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": {}
}