diff --git a/doc/Makefile b/doc/Makefile index 5f1455b85..df633dd6e 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -21,6 +21,7 @@ MANPAGES := doc/lightning-cli.1 \ doc/lightning-dev-sendcustommsg.7 \ doc/lightning-disconnect.7 \ doc/lightning-feerates.7 \ + doc/lightning-fetchinvoice.7 \ doc/lightning-fundchannel.7 \ doc/lightning-fundchannel_start.7 \ doc/lightning-fundchannel_complete.7 \ @@ -42,12 +43,14 @@ MANPAGES := doc/lightning-cli.1 \ doc/lightning-multiwithdraw.7 \ doc/lightning-newaddr.7 \ doc/lightning-notifications.7 \ + doc/lightning-offer.7 \ doc/lightning-openchannel_init.7 \ doc/lightning-openchannel_signed.7 \ doc/lightning-openchannel_update.7 \ doc/lightning-pay.7 \ doc/lightning-plugin.7 \ doc/lightning-reserveinputs.7 \ + doc/lightning-sendinvoice.7 \ doc/lightning-sendonion.7 \ doc/lightning-sendpay.7 \ doc/lightning-setchannelfee.7 \ diff --git a/doc/index.rst b/doc/index.rst index 4c5e10373..42ce06c69 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -44,6 +44,7 @@ c-lightning Documentation lightning-dev-sendcustommsg lightning-disconnect lightning-feerates + lightning-fetchinvoice lightning-fundchannel lightning-fundchannel_cancel lightning-fundchannel_complete @@ -71,6 +72,7 @@ c-lightning Documentation lightning-multiwithdraw lightning-newaddr lightning-notifications + lightning-offer lightning-openchannel_init lightning-openchannel_signed lightning-openchannel_update @@ -78,6 +80,7 @@ c-lightning Documentation lightning-ping lightning-plugin lightning-reserveinputs + lightning-sendinvoice lightning-sendonion lightning-sendpay lightning-sendpsbt diff --git a/doc/lightning-fetchinvoice.7 b/doc/lightning-fetchinvoice.7 new file mode 100644 index 000000000..65490f383 --- /dev/null +++ b/doc/lightning-fetchinvoice.7 @@ -0,0 +1,129 @@ +.TH "LIGHTNING-FETCHINVOICE" "7" "" "" "lightning-fetchinvoice" +.SH NAME +lightning-fetchinvoice - Command for fetch an invoice for an offer +.SH SYNOPSIS + +\fIEXPERIMENTAL_FEATURES only\fR + + +\fBfetchinvoice\fR \fIoffer\fR [\fImsatoshi\fR] [\fIquantity\fR] [\fIrecurrence_counter\fR] [\fIrecurrence_start\fR] [\fIrecurrence_label\fR] [\fItimeout\fR] + +.SH DESCRIPTION + +The \fBfetchinvoice\fR RPC command contacts the issuer of an \fIoffer\fR to get +an actual invoice that can be paid\. It highlights any changes between the +offer and the returned invoice\. + + +The offer must not contain \fIsend_invoice\fR; see \fBlightning-sendinvoice\fR(7)\. + + +\fImsatoshi\fR is required if the \fIoffer\fR does not specify +an amount at all, otherwise it is not allowed\. + + +\fIquantity\fR is is required if the \fIoffer\fR specifies +\fIquantity_min\fR or \fIquantity_max\fR, otherwise it is not allowed\. + + +\fIrecurrence_counter\fR is required if the \fIoffer\fR +specifies \fIrecurrence\fR, otherwise it is not allowed\. +\fIrecurrence_counter\fR should first be set to 0, and incremented for +each successive invoice in a given series\. + + +\fIrecurrence_start\fR is required if the \fIoffer\fR +specifies \fIrecurrence_base\fR with \fIstart_any_period\fR set, otherwise it +is not allowed\. It indicates what period number to start at\. + + +\fIrecurrence_label\fR is required if \fIrecurrence_counter\fR 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\. + + +\fItimeout\fR is an optional timeout; if we don't get a reply before this +we fail (default, 60 seconds)\. + +.SH RETURN VALUE + +On success, an object as follows is returned: + +.RS +.IP \[bu] +\fIinvoice\fR: the bolt12-encoded invoice string, starting with "lni1"\. +.IP \[bu] +\fIchanges\fR: an object detailing changes between the offer and invoice\. + +.RE + +Optionally: + +.RS +.IP \[bu] +\fInext_period\fR: an object returned for recurring invoices if the next +period is under the recurrence_limit (if any)\. + +.RE + +The \fIchanges\fR object can have and of the following members: + +.RS +.IP \[bu] +\fIdescription_appended\fR: extra characters appended to the \fIdescription\fR field\. +.IP \[bu] +\fIdescription\fR: a completely replaced \fIdescription\fR field\. +.IP \[bu] +\fIvendor_removed\fR": the offer vendor field, which has been omitted from the invoice\. +.IP \[bu] +\fIvendor\fR": the offer vendor field, which has changed from the invoice\. +.IP \[bu] +\fImsat\fR": the amount, if different from the offer amount multiplied +by any \fIquantity\fR (or the offer had no amount, or was not in BTC)\. + +.RE + +The \fInext_period\fR object has at least the following members: + +.RS +.IP \[bu] +\fIcounter\fR: the index of the next period to be fetchinvoice\. +.IP \[bu] +\fIstarttime\fR: the time that the next period starts (seconds since 1970) +.IP \[bu] +\fIendtime\fR: the time that the next period ends (seconds since 1970) +.IP \[bu] +\fIpaywindow_start\fR: the earliest time that the next invoice can be fetched (seconds since 1970) +.IP \[bu] +\fIpaywindow_end\fR: the latest time that the next invoice can be fetched (seconds since 1970) + +.RE + +The following error codes may occur: + +.RS +.IP \[bu] +-1: Catchall nonspecific error\. +.IP \[bu] +1002: Offer has expired\. +.IP \[bu] +1003: Cannot find a route to the node making the offer\. +.IP \[bu] +1004: The node making the offer returned an error message\. +.IP \[bu] +1005: We timed out trying to fetch an invoice\. + +.RE +.SH AUTHOR + +Rusty Russell \fI is mainly responsible\. + +.SH SEE ALSO + +\fBlightning-sendinvoice\fR(7), \fBlightning-pay\fR(7)\. + +.SH RESOURCES + +Main web site: \fIhttps://github.com/ElementsProject/lightning\fR + +\" SHA256STAMP:d891c6471a81b3b73109b19d1bc6a393bc60b5df804d6b14d330e2d8dca47f4e diff --git a/doc/lightning-fetchinvoice.7.md b/doc/lightning-fetchinvoice.7.md new file mode 100644 index 000000000..5d7f77d30 --- /dev/null +++ b/doc/lightning-fetchinvoice.7.md @@ -0,0 +1,90 @@ +lightning-fetchinvoice -- Command for fetch an invoice for an offer +=================================================================== + +SYNOPSIS +-------- + +*EXPERIMENTAL_FEATURES only* + +**fetchinvoice** *offer* \[*msatoshi*\] \[*quantity*\] \[*recurrence_counter*\] \[*recurrence_start*\] \[*recurrence_label*\] \[*timeout*\] + +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. + +The offer must not contain *send_invoice*; see lightning-sendinvoice(7). + +*msatoshi* is required if the *offer* does not specify +an amount at all, otherwise it is not allowed. + +*quantity* is is required if the *offer* specifies +*quantity_min* or *quantity_max*, otherwise it is not allowed. + +*recurrence_counter* is 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* is 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* is 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* is an optional timeout; if we don't get a reply before this +we fail (default, 60 seconds). + +RETURN VALUE +------------ + +On success, an object as follows is returned: + +* *invoice*: the bolt12-encoded invoice string, starting with "lni1". +* *changes*: an object detailing changes between the offer and invoice. + +Optionally: +* *next_period*: an object returned for recurring invoices if the next + period is under the recurrence_limit (if any). + +The *changes* object can have and of the following members: +* *description_appended*: extra characters appended to the *description* field. +* *description*: a completely replaced *description* field. +* *vendor_removed*": the offer vendor field, which has been omitted from the invoice. +* *vendor*": the offer vendor field, which has changed from the invoice. +* *msat*": the amount, if different from the offer amount multiplied + by any *quantity* (or the offer had no amount, or was not in BTC). + +The *next_period* object has at least the following members: +* *counter*: the index of the next period to be fetchinvoice. +* *starttime*: the time that the next period starts (seconds since 1970) +* *endtime*: the time that the next period ends (seconds since 1970) +* *paywindow_start*: the earliest time that the next invoice can be fetched (seconds since 1970) +* *paywindow_end*: the latest time that the next invoice can be fetched (seconds since 1970) + +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 <> is mainly responsible. + +SEE ALSO +-------- + +lightning-sendinvoice(7), lightning-pay(7). + +RESOURCES +--------- + +Main web site: + diff --git a/doc/lightning-offer.7 b/doc/lightning-offer.7 new file mode 100644 index 000000000..7396e2230 --- /dev/null +++ b/doc/lightning-offer.7 @@ -0,0 +1,162 @@ +.TH "LIGHTNING-OFFER" "7" "" "" "lightning-offer" +.SH NAME +lightning-offer - Command for accepting payments +.SH SYNOPSIS + +\fIEXPERIMENTAL_FEATURES only\fR + + +\fBoffer\fR \fIamount\fR \fIdescription\fR [\fIsend_invoice\fR] [\fIlabel\fR] [\fIvendor\fR] [\fIquantity_min\fR] [\fIquantity_max\fR] [\fIabsolute_expiry\fR] [\fIrecurrence\fR] [\fIrecurrence_base\fR] [\fIrecurrence_paywindow\fR] [\fIrecurrence_limit\fR] [\fIrefund_for\fR] [\fIsingle_use\fR] + +.SH DESCRIPTION + +The \fBoffer\fR RPC command creates an offer, which is a precursor to +one or more invoices\. It automatically enables the accepting of +corresponding invoice_request or invoice messages (depending on +\fIsend_invoice\fR)\. + + +The \fIamount\fR parameter can be the string "any", which creates an offer +that can be paid with any amount (e\.g\. a donation)\. Otherwise it can +be a positive value in millisatoshi precision; it can be a whole +number, or a whole number ending in \fImsat\fR or \fIsat\fR, or a number with +three decimal places ending in \fIsat\fR, or a number with 1 to 11 decimal +places ending in \fIbtc\fR\. + + +\fIamount\fR can also have an ISO 4217 postfix (i\.e\. USD), in which case +currency conversion will need to be done for the invoice itself\. + + +The \fIdescription\fR is a short description of purpose of the offer, +e\.g\. \fIcoffee\fR\. This value is encoded into the resulting offer and is +viewable by anyone you expose this offer to\. It must be UTF-8, and +cannot use \fI\u\fR JSON escape codes\. + + +The \fIvendor\fR is another (optional) field exposed in the offer, and +reflects who is issuing this offer (i\.e\. you) if appropriate\. + + +The \fIsend_invoice\fR boolean (default false unless \fIsingle_use\fR) creates +an offer to send money: the user of the offer will send an invoice, +rather than an invoice_request\. This is encoded in the offer\. Note +that \fIrecurrence\fR and ISO 4217 currencies are not currently +well-supported for this case! + + +The \fIlabel\fR field is an internal-use name for the offer, which can +be any UTF-8 string\. + + +The present of \fIquantity_min\fR or \fIquantity_max\fR indicates that the +invoice can specify more than one of the items within this (inclusive) +range\. The \fIamount\fR for the invoice will need to be multiplied +accordingly\. These are encoded in the offer\. + + +The \fIabsolute_expiry\fR is optionally the time the offer is valid until, +in seconds since the first day of 1970 UTC\. If not set, the offer +remains valid (though it can be deactivated by the issuer of course)\. +This is encoded in the offer\. + + +\fIrecurrence\fR means that an invoice is expected at regular intervals\. +The argument is a positive number followed by one of "seconds", +"minutes", "hours", "days", "weeks", "months" or "years" (variants +without the trailing "s" are also permitted)\. This is encoded in the +offer\. The semantics of recurrence is fairly predictable, but fully +documented in BOLT 12\. e\.g\. "4weeks"\. + + +\fIrecurrence_base\fR is an optional time in seconds since the first day +of 1970 UTC, optionally with a "@" prefix\. This indicates when the +first period begins; without this, the recurrence periods start from +the first invoice\. The "@" prefix means that the invoice must start +by paying the first period; otherwise it is permitted to start at any +period\. This is encoded in the offer\. e\.g\. "@1609459200" indicates +you must start paying on the 1st January 2021\. + + +\fIrecurrence_paywindow\fR is an optional argument of form +'-time+time[%]'\. The first time is the number of seconds before the +start of a period in which an invoice and payment is valid, the second +time is the number of seconds after the start of the period\. For +example \fI-604800+86400\fR means you can fetch an pay the invoice 4 weeks +before the given period starts, and up to 1 day afterwards\. The +optional \fI%\fR indicates that the amount of the invoice will be scaled +by the time remaining in the period\. If this is not specified, the +default is that payment is allowed during the current and previous +periods\. This is encoded in the offer\. + + +\fIrecurrence_limit\fR is an optional argument to indicate the maximum +period which exists\. eg\. "12" means there are 13 periods, from 0 to +12 inclusive\. This is encoded in the offer\. + + +\fIrefund_for\fR is the payment_preimage of a previous (paid) invoice\. +This implies \fIsend_invoice\fR and \fIsingle_use\fR\. This is encoded in the +offer\. + + +\fIsingle_use\fR (default false, unless \fIrefund_for\fR) indicates that the +invoice associated with the offer is only valid once; for a +\fIsend_invoice\fR offer many invoices can be accepted until one is +successfully paid (and we will only attempt to pay one at any time)\. +For a non-\fIsingle-use\fR offer, we will issue any number of invoices as +requested, until one is paid, at which time we will expire all the +other invoices for this offer and issue no more\. + +.SH RETURN VALUE + +On success, an object as follows is returned: + +.RS +.IP \[bu] +\fIoffer_id\fR: the hash of the offer\. +.IP \[bu] +\fIactive\fR: true +.IP \[bu] +\fIsingle_use\fR: true if \fIsingle_use\fR was specified or implied\. +.IP \[bu] +\fIbolt12\fR: the bolt12 offer, starting with "lno1" + +.RE + +Optionally: + +.RS +.IP \[bu] +\fIlabel\fR: the user-specified label\. + +.RE + +On failure, an error is returned and no offer is created\. If the +lightning process fails before responding, the caller should use +\fBlightning-listoffers\fR(7) to query whether this offer was created or +not\. + + +The following error codes may occur: + +.RS +.IP \[bu] +-1: Catchall nonspecific error\. +.IP \[bu] +1000: Offer with this offer_id already exists\. + +.RE +.SH AUTHOR + +Rusty Russell \fI is mainly responsible\. + +.SH SEE ALSO + +\fBlightning-listoffers\fR(7), \fBlightning-deloffer\fR(7)\. + +.SH RESOURCES + +Main web site: \fIhttps://github.com/ElementsProject/lightning\fR + +\" SHA256STAMP:88a1e0515adae79cdeef661b6462879d7fb0d666a7731ffdb131053c15c1b9de diff --git a/doc/lightning-offer.7.md b/doc/lightning-offer.7.md new file mode 100644 index 000000000..56c57d6fe --- /dev/null +++ b/doc/lightning-offer.7.md @@ -0,0 +1,134 @@ +lightning-offer -- Command for accepting payments +================================================= + +SYNOPSIS +-------- + +*EXPERIMENTAL_FEATURES only* + +**offer** *amount* *description* \[*send_invoice*\] \[*label*\] \[*vendor*\] \[*quantity_min*\] \[*quantity_max*\] \[*absolute_expiry*\] \[*recurrence*\] \[*recurrence_base*\] \[*recurrence_paywindow*\] \[*recurrence_limit*\] \[*refund_for*\] \[*single_use*\] + +DESCRIPTION +----------- + +The **offer** RPC command creates an offer, which is a precursor to +one or more invoices. It automatically enables the accepting of +corresponding invoice_request or invoice messages (depending on +*send_invoice*). + +The *amount* parameter can be the string "any", which creates an offer +that can be paid with any amount (e.g. a donation). Otherwise it can +be a positive value in millisatoshi precision; 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*. + +*amount* can also have an ISO 4217 postfix (i.e. USD), in which case +currency conversion will need to be done for the invoice itself. + +The *description* is a short description of purpose of the offer, +e.g. *coffee*. This value is encoded into the resulting offer and is +viewable by anyone you expose this offer to. It must be UTF-8, and +cannot use *\\u* JSON escape codes. + +The *vendor* is another (optional) field exposed in the offer, and +reflects who is issuing this offer (i.e. you) if appropriate. + +The *send_invoice* boolean (default false unless *single_use*) creates +an offer to send money: the user of the offer will send an invoice, +rather than an invoice_request. This is encoded in the offer. Note +that *recurrence* and ISO 4217 currencies are not currently +well-supported for this case! + +The *label* field is an internal-use name for the offer, which can +be any UTF-8 string. + +The present of *quantity_min* or *quantity_max* indicates that the +invoice can specify more than one of the items within this (inclusive) +range. The *amount* for the invoice will need to be multiplied +accordingly. These are encoded in the offer. + +The *absolute_expiry* is optionally the time the offer is valid until, +in seconds since the first day of 1970 UTC. If not set, the offer +remains valid (though it can be deactivated by the issuer of course). +This is encoded in the offer. + +*recurrence* means that an invoice is expected at regular intervals. +The argument is a positive number followed by one of "seconds", +"minutes", "hours", "days", "weeks", "months" or "years" (variants +without the trailing "s" are also permitted). This is encoded in the +offer. The semantics of recurrence is fairly predictable, but fully +documented in BOLT 12. e.g. "4weeks". + +*recurrence_base* is an optional time in seconds since the first day +of 1970 UTC, optionally with a "@" prefix. This indicates when the +first period begins; without this, the recurrence periods start from +the first invoice. The "@" prefix means that the invoice must start +by paying the first period; otherwise it is permitted to start at any +period. This is encoded in the offer. e.g. "@1609459200" indicates +you must start paying on the 1st January 2021. + +*recurrence_paywindow* is an optional argument of form +'-time+time\[%\]'. The first time is the number of seconds before the +start of a period in which an invoice and payment is valid, the second +time is the number of seconds after the start of the period. For +example *-604800+86400* means you can fetch an pay the invoice 4 weeks +before the given period starts, and up to 1 day afterwards. The +optional *%* indicates that the amount of the invoice will be scaled +by the time remaining in the period. If this is not specified, the +default is that payment is allowed during the current and previous +periods. This is encoded in the offer. + +*recurrence_limit* is an optional argument to indicate the maximum +period which exists. eg. "12" means there are 13 periods, from 0 to +12 inclusive. This is encoded in the offer. + +*refund_for* is the payment_preimage of a previous (paid) invoice. +This implies *send_invoice* and *single_use*. This is encoded in the +offer. + +*single_use* (default false, unless *refund_for*) indicates that the +invoice associated with the offer is only valid once; for a +*send_invoice* offer many invoices can be accepted until one is +successfully paid (and we will only attempt to pay one at any time). +For a non-*single-use* offer, we will issue any number of invoices as +requested, until one is paid, at which time we will expire all the +other invoices for this offer and issue no more. + +RETURN VALUE +------------ + +On success, an object as follows is returned: + +* *offer_id*: the hash of the offer. +* *active*: true +* *single_use*: true if *single_use* was specified or implied. +* *bolt12*: the bolt12 offer, starting with "lno1" + +Optionally: +* *label*: the user-specified label. + +On failure, an error is returned and no offer is created. If the +lightning process fails before responding, the caller should use +lightning-listoffers(7) to query whether this offer was created or +not. + +The following error codes may occur: +- -1: Catchall nonspecific error. +- 1000: Offer with this offer_id already exists. + +AUTHOR +------ + +Rusty Russell <> is mainly responsible. + +SEE ALSO +-------- + +lightning-listoffers(7), lightning-deloffer(7). + +RESOURCES +--------- + +Main web site: + diff --git a/doc/lightning-sendinvoice.7 b/doc/lightning-sendinvoice.7 new file mode 100644 index 000000000..14fdbc9e9 --- /dev/null +++ b/doc/lightning-sendinvoice.7 @@ -0,0 +1,81 @@ +.TH "LIGHTNING-SENDINVOICE" "7" "" "" "lightning-sendinvoice" +.SH NAME +lightning-sendinvoice - Command for send an invoice for an offer +.SH SYNOPSIS + +\fIEXPERIMENTAL_FEATURES only\fR + + +\fBsendinvoice\fR \fIoffer\fR [\fIlabel\fR] [\fImsatoshi\fR] [\fItimeout\fR] [\fIinvoice_timeout\fR] [\fIquantity\fR] + +.SH DESCRIPTION + +The \fBsendinvoice\fR RPC command creates and sends an invoice to the +issuer of an \fIoffer\fR for it to pay: the offer must contain +\fIsend_invoice\fR; see \fBlightning-fetchinvoice\fR(7)\. + + +\fIoffer\fR is the bolt12 offer string beginning with "lno1"\. + + +\fIlabel\fR is the unique label to use for this invoice\. + + +\fImsatoshi\fR is optional: it is required if the \fIoffer\fR does not specify +an amount at all, or specifies it in a different currency\. Otherwise +you may set it (e\.g\. to provide a tip), and if not it defaults to the +amount contained in the offer (multiplied by \fIquantity\fR if any)\. + + +\fItimeout\fR is how many seconds to wait for the offering node to pay the +invoice or return an error, default 90 seconds\. + + +\fIinvoice_timeout\fR can be set to greater than \fItimeout\fR, to give the +offering node longer to pay; in this case \fIsendinvoice\fR will time out +but the invoice will still be valid, and the caller should monitor it\. + + +\fIquantity\fR is optional: it is required if the \fIoffer\fR specifies +\fIquantity_min\fR or \fIquantity_max\fR, otherwise it is not allowed\. + +.SH RETURN VALUE + +On success, an object as follows is returned: + +.RS +.IP \[bu] +\fIinvstring\fR: the bolt12-encoded invoice string we sent (now paid), starting with "lni1"\. +.IP \[bu] +\fImsat\fR: the amount they paid\. + +.RE + +The following error codes may occur: + +.RS +.IP \[bu] +-1: Catchall nonspecific error\. +.IP \[bu] +1002: Offer has expired\. +.IP \[bu] +1003: Cannot find a route to the node making the offer\. +.IP \[bu] +1004: The node making the offer returned an error message\. +.IP \[bu] +1005: We timed out waiting for the invoice to be paid + +.RE +.SH AUTHOR + +Rusty Russell \fI is mainly responsible\. + +.SH SEE ALSO + +\fBlightning-fetchinvoice\fR(7)\. + +.SH RESOURCES + +Main web site: \fIhttps://github.com/ElementsProject/lightning\fR + +\" SHA256STAMP:0ffd4c0967f4aa7ffb2f14ed4658dbe4ef79926a08acf0534db47fdd8bd1b6bc diff --git a/doc/lightning-sendinvoice.7.md b/doc/lightning-sendinvoice.7.md new file mode 100644 index 000000000..dd68d16fe --- /dev/null +++ b/doc/lightning-sendinvoice.7.md @@ -0,0 +1,66 @@ +lightning-sendinvoice -- Command for send an invoice for an offer +================================================================= + +SYNOPSIS +-------- + +*EXPERIMENTAL_FEATURES only* + +**sendinvoice** *offer* \[*label*\] \[*msatoshi*\] \[*timeout*\] \[*invoice_timeout*\] \[*quantity*\] + +DESCRIPTION +----------- + +The **sendinvoice** RPC command creates and sends an invoice to the +issuer of an *offer* for it to pay: the offer must contain +*send_invoice*; see lightning-fetchinvoice(7). + +*offer* is the bolt12 offer string beginning with "lno1". + +*label* is the unique label to use for this invoice. + +*msatoshi* is optional: it is required if the *offer* does not specify +an amount at all, or specifies it in a different currency. Otherwise +you may set it (e.g. to provide a tip), and if not it defaults to the +amount contained in the offer (multiplied by *quantity* if any). + +*timeout* is how many seconds to wait for the offering node to pay the +invoice or return an error, default 90 seconds. + +*invoice_timeout* can be set to greater than *timeout*, to give the +offering node longer to pay; in this case *sendinvoice* will time out +but the invoice will still be valid, and the caller should monitor it. + +*quantity* is optional: it is required if the *offer* specifies +*quantity_min* or *quantity_max*, otherwise it is not allowed. + +RETURN VALUE +------------ + +On success, an object as follows is returned: + +* *invstring*: the bolt12-encoded invoice string we sent (now paid), starting with "lni1". +* *msat*: the amount they paid. + +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 waiting for the invoice to be paid + +AUTHOR +------ + +Rusty Russell <> is mainly responsible. + +SEE ALSO +-------- + +lightning-fetchinvoice(7). + +RESOURCES +--------- + +Main web site: +