FreeBSD Manual Pages
LIGHTNING-INVOICE(7) LIGHTNING-INVOICE(7) NAME lightning-invoice -- Command for accepting payments SYNOPSIS invoice amount_msat label description [expiry] [fallbacks] [preimage] [exposeprivatechannels] [cltv] [deschashonly] DESCRIPTION The invoice RPC command creates the expectation of a payment of a given amount of milli-satoshi: it returns a unique token which another light- ning daemon can use to pay this invoice. This token includes a route hint description of an incoming channel with capacity to pay the in- voice, if any exists. • amount_msat (msat_or_any): The string any, which creates an invoice that can be paid with any amount. Otherwise it is a positive value in millisatoshi precision; it can be a whole number, or a whole num- ber 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. • label (one of): A unique string or number (which is treated as a string, so 01 is different from 1); it is never revealed to other nodes on the lightning network, but it can be used to query the sta- tus of this invoice.: • (string) • (integer) • description (string): A short description of purpose of payment, e.g. 1 cup of coffee. This value is encoded into the BOLT11 invoice and is viewable by any node you send this invoice to (unless de- schashonly is true as described below). It must be UTF-8, and cannot use \u JSON escape codes. • expiry (u64, optional): The time the invoice is valid for, in sec- onds. If no value is provided the default of 604800 (1 week) is used. • fallbacks (array of strings, optional): One or more fallback ad- dresses to include in the invoice (in order from most- preferred to least): note that these arrays are not currently tracked to fulfill the invoice.: • (string, optional) • preimage (hex, optional): A 64-digit hex string to be used as pay- ment preimage for the created invoice. By default, if unspecified, lightningd will generate a secure pseudorandom preimage seeded from an appropriate entropy source on your system. IMPORTANT: if you specify the preimage, you are responsible, to ensure appropriate care for generating using a secure pseudorandom generator seeded with sufficient entropy, and keeping the preimage secret. This para- meter is an advanced feature intended for use with cutting-edge cryptographic protocols and should not be used unless explicitly needed. • exposeprivatechannels (one of, optional): If specified, it overrides the default route hint logic, which will use unpublished channels only if there are no published channels.: • (boolean): If True unpublished channels are always considered as a route hint candidate; if False, never. • (array of short_channel_ids): Array of short channel ids (or a remote alias), only those specific channels will be considered candidates, even if they are public or dead-ends. • (short_channel_id, optional) • (short_channel_id): If it is a short channel id (e.g. 1x1x3), only this specific channel will be considered candidate, even if it is public or dead-end. • cltv (u32, optional): If specified, sets the min_final_cltv_expiry for the invoice. Otherwise, it's set to the parameter cltv-final. • deschashonly (boolean, optional): If True, then the bolt11 returned contains a hash of the description, rather than the description it- self: this allows much longer descriptions, but they must be commu- nicated via some other mechanism. The default is False. RETURN VALUE On success, an object is returned, containing: • bolt11 (string): The bolt11 string. • payment_hash (hash): The hash of the payment_preimage which will prove payment. • payment_secret (secret): The payment_secret to place in the onion. • expires_at (u64): UNIX timestamp of when invoice expires. • created_index (u64): 1-based index indicating order this invoice was created in. (added v23.08) The following warnings may also be returned: • warning_capacity: Even using all possible channels, there's not enough incoming capacity to pay this invoice. • warning_offline: There would be enough incoming capacity, but some channels are offline, so there isn't. • warning_deadends: There would be enough incoming capacity, but some channels are dead-ends (no other public channels from those peers), so there isn't. • warning_private_unused: There would be enough incoming capacity, but some channels are unannounced and exposeprivatechannels is false, so there isn't. • warning_mpp: There is sufficient capacity, but not in a single chan- nel, so the payer will have to use multi-part payments. ERRORS On failure, an error is returned and no invoice is created. If the lightning process fails before responding, the caller should use light- ning-listinvoices(7) to query whether this invoice was created or not. The following error codes may occur: • -1: Catchall nonspecific error. • 900: An invoice with the given label already exists. • 901: An invoice with the given preimage already exists. • 902: None of the specified exposeprivatechannels were usable. AUTHOR Rusty Russell <<rusty@rustcorp.com.au>> is mainly responsible. SEE ALSO lightning-listinvoices(7), lightning-delinvoice(7), lightning-pay(7) RESOURCES Main web site: <https://github.com/ElementsProject/lightning> EXAMPLES Example 1: Request: $ lightning-cli invoice -k "amount_msat"=10000 "label"="lbl_l31" "description"="Invoice description l31" { "id": "example:invoice#1", "method": "invoice", "params": { "amount_msat": 10000, "label": "lbl_l31", "description": "Invoice description l31" } } Response: { "payment_hash": "paymenthashinvl0310031003100310031003100310031003100310031003100", "expires_at": 1739000000, "bolt11": "lnbcrt100n1pnt2bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000", "payment_secret": "paymentsecretinvl00310003100031000310003100031000310003100031000", "created_index": 2 } Example 2: Request: $ lightning-cli invoice -k "amount_msat"="50000msat" "label"="lbl_l32" "description"="l32 description" { "id": "example:invoice#2", "method": "invoice", "params": { "amount_msat": "50000msat", "label": "lbl_l32", "description": "l32 description" } } Response: { "payment_hash": "paymenthashinvl0320032003200320032003200320032003200320032003200", "expires_at": 1739000000, "bolt11": "lnbcrt100n1pnt2bolt11invl032000000000bolt11invl032000000000bolt11invl032000000000bolt11invl032000000000bolt11invl032000000000bolt11invl032000000000bolt11invl032000000000bolt11invl032000000000bolt11invl032000000000bolt11invl032000000000", "payment_secret": "paymentsecretinvl00032003200320032003200320032003200320032003200", "created_index": 3 } Core Lightning v25.02 LIGHTNING-INVOICE(7)
NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | AUTHOR | SEE ALSO | RESOURCES | EXAMPLES
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=lightning-invoice&sektion=7&manpath=FreeBSD+Ports+14.3.quarterly>