LIGHTNING-OFFER(7)

📦

version 26.06.9 · 2 versions

26.06.9 · nixpkgs unstable (latest)
26.04.1 · nixos 26.05

💖 NAME

okay so bestie, this is lightning-offer(7) — the offer command, aka the one that makes you able to accept payments. slay.

✨ SYNOPSIS

offer amount [description] [issuer] [label] [quantity_max]
[absolute_expiry] [recurrence] [recurrence_base] [recurrence_paywindow]
[recurrence_limit] [single_use] [proportional_amount]
[optional_recurrence] [fronting_nodes]

🎀 DESCRIPTION

ok so the offer RPC command literally creates an offer (or hands you back one that already exists), and an offer is like the precursor to creating one or more invoices. the way it works: it automatically switches on the processing of an incoming invoice_request, and the issuing of invoices. it's giving main character energy for the whole payment flow ✨

💡 heads up bestie — if you're trying to make an offer to pay someone else, that's a different thing entirely, go see lightning-invoicerequest(7).

amount (one of these): can be the string any, which makes an offer that can be paid with any amount (think: a donation 🫶). otherwise it's a positive value with 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 (like USD), and in that case currency conversion will need to happen for the invoice itself. you need a plugin that provides the currencyconvert API for that currency, otherwise the offer creation will just fail, no cap:
- (msat_or_any)
- (currency)
description (string, optional): a short lil description of what the offer is for, like coffee. this value gets encoded into the resulting offer and is viewable by literally anyone you expose this offer to. it must be UTF-8, and it cannot use \u JSON escape codes.
issuer (string, optional): who's issuing this offer (i.e. you, bestie) if appropriate.
label (string, optional): an internal-use name for the offer, can be any UTF-8 string. this is NOT encoded in the offer not sent to the issuer. 🙈
quantity_max (u64, optional): the invoice can specify more than one of the items up to (and including) this maximum. 0 is a special value meaning no maximuim. the amount for the invoice will need to be multiplied accordingly. this is encoded in the offer.
absolute_expiry (u64, optional): the time the offer is valid until, in seconds since the first day of 1970 UTC. if it's not set, the offer remains valid (though of course the issuer can still deactivate it). this is encoded in the offer.
recurrence (string, optional): an invoice is expected at regular intervals 🔁. the argument is a positive number followed by one of seconds, minutes, hours, days, weeks, or months (variants without the trailing s are also permitted). this is encoded in the offer. the semantics of recurrence are 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 the 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 and 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. e.g. 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 offer). 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 comes back 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 (reflects 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-listoffers(7) to query whether this offer was created or not. (yes bestie, go check. don't guess.)

if the offer already existed and is still active, that one 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. (thank him, he's iconic 👑)

🌈 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": "lno1qgsq000bolt210002100021000210002100021000210002100021000210002100021000210002100021000210002100021000210002100021000210002100021000210002100021000",
  "used": false,
  "created": true
}

Example 2: