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

FreeBSD Manual Pages


home | help
LIGHTNING-INVOICE(7)	       lightning-invoice	  LIGHTNING-INVOICE(7)

       lightning-invoice - Command for accepting payments

       invoice msatoshi	label description [expiry] [fallbacks] [preimage] [ex-

       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.

       The msatoshi parameter can be the string	"any", which  creates  an  in-
       voice  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
       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.

       The label must be 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	status
       of this invoice.

       The  description	 is  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. It must be UTF-8, and
       cannot use  JSON	escape codes.

       The expiry is optionally	the time the invoice is	valid for;  without  a
       suffix  it  is interpreted as seconds, otherwise	suffixes s, m, h, d, w
       indicate	seconds, minutes, hours, days and weeks	respectively.	If  no
       value is	provided the default of	604800 (1w) is used.

       The fallbacks array is one or more fallback addresses to	include	in the
       invoice (in order from most-preferred to	least):	note that these	arrays
       are not currently tracked to fulfill the	invoice.

       The  preimage  is  a 64-digit hex string	to be used as payment preimage
       for the created invoice.	By default, if	unspecified,  lightningd  will
       generate	 a secure pseudorandom preimage	seeded from an appropriate en-
       tropy 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 keep-
       ing the preimage	secret.	This parameter is an advanced feature intended
       for use with cutting-edge cryptographic protocols  and  should  not  be
       used unless explicitly needed.

       If  specified,  exposeprivatechannels  overrides	the default route hint
       logic, which will use unpublished channels only if there	 are  no  pub-
       lished  channels. If true unpublished channels are always considered as
       a route hint candidate; if false, never.	 If it is a short  channel  id
       (e.g.  1x1x3)  or array of short	channel	ids, only those	specific chan-
       nels will be considered candidates, even	if they	are  public  or	 dead-

       The  route hint is selected from	the set	of incoming channels of	which:
       peeras balance minus their reserves is at least msatoshi, state is nor-
       mal,  the  peer	is connected and not a dead end	(i.e. has at least one
       other public channel). The selection uses some  randomness  to  prevent
       probing,	 but  favors channels that become more balanced	after the pay-

       On success, a hash is returned as  payment_hash	to  be	given  to  the
       payer,  and  the	 expiry_time  as  a  UNIX timestamp. It	also returns a
       BOLT11 invoice as bolt11	to be given to the payer.

       On failure, an error is returned	and no	invoice	 is  created.  If  the
       lightning process fails before responding, the caller should use	light-
       ning-listinvoice(7) to query whether this invoice was created or	not.

       The following error codes may occur:

	      o	     -1: Catchall nonspecific error.

	      o	     900: An invoice with the given label already exists.

	      o	     901: An invoice with the given preimage already exists.

	      o	     902: None of the specified	exposeprivatechannels were us-

       One of the following warnings may occur (on success):

	      o	     warning_offline  if no channel with a currently connected
		     peer has
		       the incoming capacity to	pay this invoice

	      o	     warning_capacity if there is no channel that  has	suffi-
		       incoming	capacity

	      o	     warning_deadends  if  there  is  no channel that is not a

       Rusty Russell> is	mainly responsible.

       lightning-listinvoice(7),      lightning-delinvoice(7),	    lightning-
       getroute(7), lightning-sendpay(7).

       Main web	site:



Want to link to this manual page? Use this URL:

home | help