mirrors/core-lightning
1
0
Fork 0
mirror of https://github.com/ElementsProject/lightning.git synced 2025-02-23 23:06:44 +01:00
Code Issues Projects Releases Wiki Activity
core-lightning/doc/schemas/lightning-listinvoices.json
ShahanaFarooqui 9592facf83 doc: Lock example values 
Changelog-Added: Test script generates all RPC documentation examples now.
2024-11-26 21:45:19 +10:30

408 lines
14 KiB
JSON
Raw Blame History

{
"$schema": "../rpc-schema-draft.json",
"type": "object",
"rpc": "listinvoices",
"title": "Command for querying invoice status",
"description": [
"The **listinvoices** RPC command gets the status of a specific invoice, if it exists, or the status of all invoices if given no argument.",
"",
"Only one of the query parameters can be used from *label*, *invstring*, *payment_hash*, or *offer_id*."
],
"categories": [
"readonly"
],
"request": {
"required": [],
"additionalProperties": false,
"properties": {
"label": {
"oneOf": [
{
"type": "string"
},
{
"type": "integer"
}
],
"description": [
"A label used a the creation of the invoice to get a specific invoice."
]
},
"invstring": {
"type": "string",
"description": [
"The string value to query a specific invoice."
]
},
"payment_hash": {
"type": "hex",
"description": [
"A payment_hash of the invoice to get the details of a specific invoice."
]
},
"offer_id": {
"type": "string",
"description": [
"A local `offer_id` the invoice was issued for a specific invoice details."
]
},
"index": {
"type": "string",
"added": "v23.08",
"enum": [
"created",
"updated"
],
"description": [
"If neither *in_channel* nor *out_channel* is specified, it controls ordering."
],
"default": "`created`"
},
"start": {
"type": "u64",
"added": "v23.08",
"description": [
"If `index` is specified, `start` may be specified to start from that value, which is generally returned from lightning-wait(7)."
]
},
"limit": {
"type": "u32",
"added": "v23.08",
"description": [
"If `index` is specified, `limit` can be used to specify the maximum number of entries to return."
]
}
},
"dependentUpon": {
"index": [
"start",
"limit"
]
}
},
"response": {
"required": [
"invoices"
],
"additionalProperties": false,
"properties": {
"invoices": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"required": [
"label",
"created_index",
"payment_hash",
"status",
"expires_at"
],
"properties": {
"label": {
"type": "string",
"description": [
"Unique label supplied at invoice creation."
]
},
"description": {
"type": "string",
"description": [
"Description used in the invoice."
]
},
"payment_hash": {
"type": "hash",
"description": [
"The hash of the *payment_preimage* which will prove payment."
]
},
"status": {
"type": "string",
"enum": [
"unpaid",
"paid",
"expired"
],
"description": [
"Whether it's paid, unpaid or unpayable."
]
},
"expires_at": {
"type": "u64",
"description": [
"UNIX timestamp of when it will become / became unpayable."
]
},
"amount_msat": {
"type": "msat",
"description": [
"The amount required to pay this invoice."
]
},
"bolt11": {
"type": "string",
"description": [
"The BOLT11 string (always present unless *bolt12* is)."
]
},
"bolt12": {
"type": "string",
"description": [
"The BOLT12 string (always present unless *bolt11* is)."
]
},
"local_offer_id": {
"type": "hash",
"description": [
"The *id* of our offer which created this invoice."
]
},
"invreq_payer_note": {
"type": "string",
"description": [
"The optional *invreq_payer_note* from invoice_request which created this invoice."
]
},
"created_index": {
"type": "u64",
"added": "v23.08",
"description": [
"1-based index indicating order this invoice was created in."
]
},
"updated_index": {
"type": "u64",
"added": "v23.08",
"description": [
"1-based index indicating order this invoice was changed (only present if it has changed since creation)."
]
}
},
"allOf": [
{
"if": {
"additionalProperties": true,
"properties": {
"status": {
"type": "string",
"enum": [
"paid"
]
}
}
},
"then": {
"additionalProperties": false,
"required": [
"pay_index",
"amount_received_msat",
"paid_at",
"payment_preimage"
],
"properties": {
"label": {},
"description": {},
"payment_hash": {},
"status": {},
"msatoshi": {},
"amount_msat": {},
"bolt11": {},
"bolt12": {},
"local_offer_id": {},
"invreq_payer_note": {},
"expires_at": {},
"created_index": {},
"updated_index": {},
"pay_index": {
"type": "u64",
"description": [
"Unique incrementing index for this payment."
]
},
"amount_received_msat": {
"type": "msat",
"description": [
"The amount actually received (could be slightly greater than *amount_msat*, since clients may overpay)."
]
},
"paid_at": {
"type": "u64",
"description": [
"UNIX timestamp of when it was paid."
]
},
"paid_outpoint": {
"type": "object",
"description": [
"Outpoint this invoice was paid with."
],
"added": "v23.11",
"additionalProperties": false,
"required": [
"txid",
"outnum"
],
"properties": {
"txid": {
"added": "v23.11",
"type": "txid",
"description": [
"ID of the transaction that paid the invoice."
]
},
"outnum": {
"added": "v23.11",
"type": "u32",
"description": [
"The 0-based output number of the transaction that paid the invoice."
]
}
}
},
"payment_preimage": {
"type": "secret",
"description": [
"Proof of payment."
]
}
}
},
"else": {
"additionalProperties": false,
"properties": {
"label": {},
"description": {},
"payment_hash": {},
"status": {},
"msatoshi": {},
"amount_msat": {},
"bolt11": {},
"bolt12": {},
"local_offer_id": {},
"invreq_payer_note": {},
"created_index": {},
"updated_index": {},
"expires_at": {}
}
}
}
]
}
}
}
},
"author": [
"Rusty Russell <<rusty@rustcorp.com.au>> is mainly responsible."
],
"see_also": [
"lightning-waitinvoice(7)",
"lightning-delinvoice(7)",
"lightning-invoice(7)"
],
"resources": [
"Main web site: <https://github.com/ElementsProject/lightning>"
],
"examples": [
{
"request": {
"id": "example:listinvoices#1",
"method": "listinvoices",
"params": {
"label": "lbl_l21"
}
},
"response": {
"invoices": [
{
"label": "lbl_l21",
"bolt11": "lnbcrt100n1pnt2bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000",
"payment_hash": "paymenthashinvl0210021002100210021002100210021002100210021002100",
"status": "paid",
"pay_index": 4,
"amount_received_msat": 400000,
"paid_at": 1738500000,
"payment_preimage": "paymentpreimager010101010101010101010101010101010101010101010101",
"description": "l21 description",
"expires_at": 1739000000,
"created_index": 2,
"updated_index": 4
}
]
}
},
{
"request": {
"id": "example:listinvoices#2",
"method": "listinvoices",
"params": {}
},
"response": {
"invoices": [
{
"label": "lbl balance l1 to l2",
"bolt11": "lnbcrt222n1pnt3005720bolt114000101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101",
"payment_hash": "paymenthashdelpay10101010101010101010101010101010101010101010101",
"amount_msat": 500000000,
"status": "paid",
"pay_index": 1,
"amount_received_msat": 500000000,
"paid_at": 1738500000,
"payment_preimage": "paymentpreimgdp1010101010101010101010101010101010101010101010101",
"description": "description send some sats l1 to l2",
"expires_at": 1739000000,
"created_index": 1,
"updated_index": 1
},
{
"label": "lbl_l21",
"bolt11": "lnbcrt100n1pnt2bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000",
"payment_hash": "paymenthashinvl0210021002100210021002100210021002100210021002100",
"status": "paid",
"pay_index": 4,
"amount_received_msat": 400000,
"paid_at": 1738510000,
"payment_preimage": "paymentpreimager010101010101010101010101010101010101010101010101",
"description": "l21 description",
"expires_at": 1739010000,
"created_index": 2,
"updated_index": 4
},
{
"label": "lbl_l22",
"bolt11": "lnbcrt100n1pnt2bolt11invl020200000000bolt11invl020200000000bolt11invl020200000000bolt11invl020200000000bolt11invl020200000000bolt11invl020200000000bolt11invl020200000000bolt11invl020200000000bolt11invl020200000000bolt11invl020200000000",
"payment_hash": "paymenthashinvl0220022002200220022002200220022002200220022002200",
"amount_msat": 200000,
"status": "unpaid",
"description": "l22 description",
"expires_at": 1739020000,
"created_index": 3,
"paid_at": 1738520000
},
{
"label": "label inv_l24",
"bolt11": "lnbcrt100n1pnt2bolt11invl020400000000bolt11invl020400000000bolt11invl020400000000bolt11invl020400000000bolt11invl020400000000bolt11invl020400000000bolt11invl020400000000bolt11invl020400000000bolt11invl020400000000bolt11invl020400000000",
"payment_hash": "paymenthashinvl0240024002400240024002400240024002400240024002400",
"amount_msat": 123000,
"status": "unpaid",
"description": "description inv_l24",
"expires_at": 1739030000,
"created_index": 4,
"paid_at": 1738530000
},
{
"label": "label inv_l25",
"bolt11": "lnbcrt100n1pnt2bolt11invl020500000000bolt11invl020500000000bolt11invl020500000000bolt11invl020500000000bolt11invl020500000000bolt11invl020500000000bolt11invl020500000000bolt11invl020500000000bolt11invl020500000000bolt11invl020500000000",
"payment_hash": "paymenthashinvl0250025002500250025002500250025002500250025002500",
"amount_msat": 124000,
"status": "unpaid",
"description": "description inv_l25",
"expires_at": 1739040000,
"created_index": 5,
"paid_at": 1738540000
}
]
}
}
]
}
Reference in a new issue View git blame Copy permalink