Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
LIGHTNING-FETCHINVOICE(7)			     LIGHTNING-FETCHINVOICE(7)

NAME
       lightning-fetchinvoice -- Command for fetch an invoice for an offer

SYNOPSIS
       fetchinvoice  offer  [amount_msat] [quantity] [recurrence_counter] [re-
       currence_start] [recurrence_label] [timeout] [payer_note]  [payer_meta-
       data] [bip353]

DESCRIPTION
       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  is-
	  suer).
         quantity  (u64,  optional):  Required	 if  the offer specifies quan-
	  tity_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 al-
	  lowed. 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 ) indicat-
	  ing 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.
         changes (object): Summary of changes from offer.:

	    description_appended  (string,  optional):	 Extra	characters ap-
	     pended 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.
         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.

AUTHOR
       Rusty Russell <<rusty@rustcorp.com.au>> is mainly responsible.

SEE ALSO
       lightning-sendinvoice(7), lightning-pay(7)

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": {}
       }

Core Lightning v25.02				     LIGHTNING-FETCHINVOICE(7)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=lightning-fetchinvoice&sektion=7&manpath=FreeBSD+Ports+14.3.quarterly>

home | help