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

NAME
     offer -- Command for accepting payments

SYNOPSIS
     offer  amount  [description]  [issuer] [label] [quantity_max] [absolute_ex-
     piry]   [recurrence]   [recurrence_base]	[recurrence_paywindow]	 [recur-
     rence_limit]   [single_use]   [proportional_amount]   [optional_recurrence]
     [fronting_nodes]

DESCRIPTION
     The offer RPC command creates an offer (or returns an existing one),  which
     is  a  precursor to creating one or more invoices. It automatically enables
     the processing of an incoming invoice_request, and issuing of invoices.

     Note that for making an offer to  pay  someone  else,  see  lightning-  in-
     voicerequest(7).

     *	amount	(one of): 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  posi-
	tive  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. It can also have an ISO 4217 postfix (e.g. USD), in which case cur-
	rency conversion will need to be done for the invoice itself.  A  plugin
	is needed which provides the currencyconvert API for this currency, oth-
	erwise the offer creation will fail.:
	*  (msat_or_any)
	*  (currency)
     *	description  (string,  optional):  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.
     *	issuer (string, optional): Who is issuing this offer (i.e. you)  if  ap-
	propriate.
     *	label  (string, optional): An internal-use name for the offer, which can
	be any UTF-8 string. This is NOT encoded in the offer not  sent  to  the
	issuer.
     *	quantity_max  (u64,  optional): Invoice can specify more than one of the
	items up (and including) this maximum: 0 is a special value  meaning  no
	maximuim.  The amount for the invoice will need to be multiplied accord-
	ingly. This is encoded in the offer.
     *	absolute_expiry (u64, optional): Time the offer is valid  until,in  sec-
	onds  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  (string, optional): An invoice is expected at regular inter-
	vals. The argument is a positive number followed by one of seconds, min-
	utes, hours, days, weeks, or months (variants without the trailing s are
	also permitted). This is encoded in the offer. The semantics  of  recur-
	rence  is  fairly  predictable,  but  fully  documented in BOLT 12. e.g.
	4weeks.
     *	recurrence_base (integer, optional): Time in seconds since the first day
	of 1970 UTC. This indicates when the first period begins; without  this,
	the recurrence periods start from the first invoice.
     *	recurrence_paywindow  (string,	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. This  is
	encoded  in the offer. The default is that payment is allowed during the
	current and previous periods.
     *	recurrence_limit (u32, optional): 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.
     *	single_use (boolean, optional): Indicates that the offer is  only  valid
	once;  we  may	issue  multiple invoices, but as soon as one is paid all
	other invoices will be expired (i.e. only one person can  pay  this  of-
	fer). The default is False.
     *	proportional_amount (boolean, optional): Payment will be charged for the
	initial period proportional to the amount remaining (only makes sense if
	recurrence_base is specified) (added v25.09)
     *	optional_recurrence  (boolean,	optional): Make recurrence optional, for
	backwards compatibility  (older  payers  will  only  pay  once).  (added
	v25.09)
     *	fronting_nodes	(array	of pubkeys, optional): An optional array of peer
	nodes to create blinded paths from.  One of  these  blinded  paths  will
	also  be used for the invoice, when they request it.  This overrides the
	payment-fronting-node configuration setting.  If set to the empty array,
	this means no fronting nodes. The default is  The  payment-fronting-node
	configuration setting. (added v26.04):
	*  (pubkey, optional)

RETURN VALUE
     On success, an object is returned, containing:

     *	offer_id  (hash):  The	id  of	this offer (merkle hash of non-signature
	fields).
     *	active (boolean) (always true): Whether this can still be used.
     *	single_use (boolean): Whether this expires as soon  as	it's  paid  (re-
	flects the single_use parameter).
     *	bolt12 (string): The bolt12 encoding of the offer.
     *	used (boolean): True if an associated invoice has been paid.
     *	created (boolean): False if the offer already existed.
     *	force_paths (boolean, optional): True if fronting_nodes (or the payment-
	fronting-node  configuration  entry)  is set: implies any invoice issued
	for this offer must use a subset  of  the  same  blinded  paths.  (added
	v26.04)
     *	label (string, optional): The (optional) user-specified label.

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

     If  the  offer  already  existed, and is still active, that is returned; if
     it's not active then this call fails.

     *	-1: Catchall nonspecific error.
     *	1000: Offer with this offer_id already exists (but is not active).

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

SEE ALSO
     lightning-listoffers(7),	   lightning-disableoffer(7),	   lightning-in-
     voicerequest(7)

RESOURCES
     Main web site: https://github.com/ElementsProject/lightning

EXAMPLES
     Example 1:

     Request:

     $ lightning-cli offer -k "amount"="10000msat" "description"="Fish sale!"

     {
       "id": "example:offer#1",
       "method": "offer",
       "params": {
	 "amount": "10000msat",
	 "description": "Fish sale!"
       }
     }

     Response:

     {
       "offer_id": "offeridl21000002100000210000021000002100000210000021000002100000",
       "active": true,
       "single_use": false,
       "bolt12": "lno1qgsq000bolt210002100021000210002100021000210002100021000210002100021000210002100021000210002100021000210002100021000210002100021000",
       "used": false,
       "created": true
     }

     Example 2:

     Request:

     $ lightning-cli offer -k "amount"="1000sat" "description"="Coffee" "quantity_max"=10

     {
       "id": "example:offer#2",
       "method": "offer",
       "params": {
	 "amount": "1000sat",
	 "description": "Coffee",
	 "quantity_max": 10
       }
     }

     Response:

     {
       "offer_id": "offeridl22000002200000220000022000002200000220000022000002200000",
       "active": true,
       "single_use": false,
       "bolt12": "lno1qgsq000bolt220002200022000220002200022000220002200022000220002200022000220002200022000220002200022000220002200022000220002200022000",
       "used": false,
       "created": true
     }

Core Lightning v26.06.1 				      LIGHTNING-OFFER(7)
home | help