diff --git a/47.md b/47.md index 13037cb556..b0b4d7464b 100644 --- a/47.md +++ b/47.md @@ -187,7 +187,7 @@ Request: "method": "pay_invoice", "params": { "invoice": "lnbc50n1...", // bolt11 invoice - "amount": 123, // invoice amount in msats, optional + "amount": 123, // invoice amount in msats, optional if the bolt11 invoice contains an amount "metadata": {} // generic metadata that can be used to add things like zap/boostagram details for a payer name/comment/etc, optional } } @@ -217,7 +217,7 @@ Request: "method": "multi_pay_invoice", "params": { "invoices": [ - {"id":"4da52c32a1", "invoice": "lnbc1...", "amount": 123}, // bolt11 invoice and amount in msats, amount is optional + {"id":"4da52c32a1", "invoice": "lnbc1...", "amount": 123}, // bolt11 invoice and amount in msats, amount is optional if the bolt11 invoice contains an amount {"id":"3da52c32a1", "invoice": "lnbc50n1...", "metadata": {} }, // generic metadata that can be used to add things like zap/boostagram details for a payer name/comment/etc, optional ], } @@ -375,8 +375,11 @@ Response: "invoice": "string", // encoded invoice, optional "description": "string", // invoice's description, optional "description_hash": "string", // invoice's description hash, optional + "offer_issuer": "string", // offer's issuer for a bolt12 transaction, optional + "payer_note": "string", // note from payer for a bolt12 transaction, optional "preimage": "string", // payment's preimage, optional if unpaid "payment_hash": "string", // Payment hash for the payment + "offer_id": "string", // the id of the offer, for a bolt12 invoice, optional "amount": 123, // value in msats "fees_paid": 123, // value in msats "created_at": unixtimestamp, // invoice/payment creation time @@ -424,8 +427,11 @@ Response: "invoice": "string", // encoded invoice, optional "description": "string", // invoice's description, optional "description_hash": "string", // invoice's description hash, optional + "offer_issuer": "string", // offer's issuer for a bolt12 transaction, optional + "payer_note": "string", // note from payer for a bolt12 transaction, optional "preimage": "string", // payment's preimage, optional if unpaid "payment_hash": "string", // Payment hash for the payment + "offer_id": "string", // the id of the offer, for a bolt12 invoice, optional "amount": 123, // value in msats "fees_paid": 123, // value in msats "created_at": unixtimestamp, // invoice/payment creation time @@ -458,6 +464,123 @@ Response: } ``` +### `pay_offer` + +Description: Requests payment of an invoice. + +Request: +```jsonc +{ + "method": "pay_offer", + "params": { + "offer": "lno1pgx...", // bolt12 offer + "amount": 123, // invoice amount in msats, optional if the bolt12 offer contains an amount + "payer_note": "string", // note to be included for the bolt12 invoice, optional + } +} +``` + +Response: +```jsonc +{ + "result_type": "pay_offer", + "result": { + "preimage": "0123456789abcdef...", // preimage of the payment + "fees_paid": 123, // value in msats, optional + } +} +``` + +Errors: +- `PAYMENT_FAILED`: The payment failed. This may be due to a timeout, exhausting all routes, insufficient capacity or similar. + +### `make_offer` + +Request: +```jsonc +{ + "method": "make_offer", + "params": { + "currency": "ABC", // ISO 4217 code of the currency (3 characters), optional (missing means msat) + "currency_minor_unit": 123, // number of decimals to apply to the amount, for currency different than msat, optional + "amount": 123, // minimum amount value, after adjustment by currency_minor_unit if applicable, optional + "description": "string", // offer's description, optional + "issuer": "string", // offer's issuer, optional + "absolute_expiry": unixtimestamp, // absolute expiry time of the offer, optional + "single_use": false // only allow the offer to be used once, optional, default false + } +} +``` + +Response: +```jsonc +{ + "result_type": "make_offer", + "result": { + "offer": "lno1pgx...", // encoded offer + "description": "string", // offer's description, optional + "issuer": "string", // offer's issuer, optional + "currency": "ABC", // ISO 4217 code of the currency (3 characters), optional (missing means msat) + "currency_minor_unit": 123, // number of decimals to apply to the amount, for currency different than msat, optional + "amount": 123, // minimum amount value, after adjustment by currency_minor_unit if applicable, optional + "offer_id": "string", // the id of the offer + "single_use": false, // whether the offer can only be used once + "used": false, // whether the offer has been used + "created_at": unixtimestamp, // offer creation time + "expires_at": unixtimestamp // offer absolute expiry time, optional + } +} +``` + +Errors: +- `EXISTED_ALREADY`: The offer could not be created because it already existed. + +### `list_offers` + +Lists offers. The `from` and `until` parameters are timestamps in seconds since epoch. If `from` is not specified, it defaults to 0. +If `until` is not specified, it defaults to the current time. Offers are returned in descending order of creation time. If none of these +parameters, as well as the "offset" parameter are not used, an offer can also be optionally selected using the `offer_id` parameter. + +Request: +```jsonc +{ + "method": "list_offers", + "params": { + "from": 1693876973, // starting timestamp in seconds since epoch (inclusive), optional + "until": 1703225078, // ending timestamp in seconds since epoch (inclusive), optional + "limit": 10, // maximum number of invoices to return, optional + "offset": 0, // offset of the first invoice to return, optional + "offer_id": "string", // the id of the offer to get details for, optional + "single_use": false, // whether the offer can only be used once, optional + "used": false // whether the offer has been used, optional +} +} +``` + +Response: +```jsonc +{ + "result_type": "list_offers", + "result": { + "offers": [ + { + "offer": "lno1pgx...", // encoded offer + "description": "string", // offer's description, optional + "issuer": "string", // offer's issuer, optional + "currency": "ABC", // ISO 4217 code of the currency (3 characters), optional (missing means msat) + "currency_minor_unit": 123, // number of decimals to apply to the amount, for currency different than msat, optional + "amount": 123, // minimum amount value, after adjustment by currency_minor_unit if applicable, optional + "offer_id": "string", // the id of the offer + "single_use": false, // whether the offer can only be used once + "used": false, // whether the offer has been used + "created_at": unixtimestamp, // offer creation time + "expires_at": unixtimestamp // offer absolute expiry time, optional + } + ], + }, +} +``` + ### `get_info` Request: @@ -479,7 +602,7 @@ Response: "network": "string", // mainnet, testnet, signet, or regtest "block_height": 1, "block_hash": "hex string", - "methods": ["pay_invoice", "get_balance", "make_invoice", "lookup_invoice", "list_transactions", "get_info"], // list of supported methods for this connection + "methods": ["pay_invoice", "get_balance", "make_invoice", "lookup_invoice", "list_transactions", "pay_offer", "make_offer", "list_offers", "get_offer_info", "get_info"], // list of supported methods for this connection "notifications": ["payment_received", "payment_sent"], // list of supported notifications for this connection, optional. } } @@ -501,8 +624,11 @@ Notification: "invoice": "string", // encoded invoice "description": "string", // invoice's description, optional "description_hash": "string", // invoice's description hash, optional + "offer_issuer": "string", // offer's issuer for a bolt12 transaction, optional + "payer_note": "string", // note from payer for a bolt12 transaction, optional "preimage": "string", // payment's preimage "payment_hash": "string", // Payment hash for the payment + "offer_id": "string", // the id of the offer, for a bolt12 invoice, optional "amount": 123, // value in msats "fees_paid": 123, // value in msats "created_at": unixtimestamp, // invoice/payment creation time @@ -527,6 +653,8 @@ Notification: "invoice": "string", // encoded invoice "description": "string", // invoice's description, optional "description_hash": "string", // invoice's description hash, optional + "offer_issuer": "string", // offer's issuer for a bolt12 transaction, optional + "payer_note": "string", // note from payer for a bolt12 transaction, optional "preimage": "string", // payment's preimage "payment_hash": "string", // Payment hash for the payment "amount": 123, // value in msats