mirror of
https://github.com/ElementsProject/lightning.git
synced 2025-02-21 14:24:09 +01:00
331 lines
10 KiB
JSON
331 lines
10 KiB
JSON
{
|
|
"$schema": "../rpc-schema-draft.json",
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"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": [],
|
|
"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"
|
|
],
|
|
"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 (**experimental-offers** only)."
|
|
]
|
|
},
|
|
"invreq_payer_note": {
|
|
"type": "string",
|
|
"description": [
|
|
"The optional *invreq_payer_note* from invoice_request which created this invoice (**experimental-offers** only)."
|
|
]
|
|
},
|
|
"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": {
|
|
"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": "xEoCR94SIz6UIRUEkxum"
|
|
}
|
|
},
|
|
"response": {
|
|
"invoices": [
|
|
{
|
|
"label": "xEoCR94SIz6UIRUEkxum",
|
|
"bolt11": "lnbcrt110u1pjmr5lzsp5sfjyj3xn7ux592k36hmmt4ax98n6lgct22wvj54yck0upcmep63qpp5qu436g855lr40ftdt7csatk5pdvtdzzfmfqluwtvm0fds95jsadqdpq0pzk7s6j8y69xjt6xe25j5j4g44hsatdxqyjw5qcqp99qxpqysgquwma3zrw4cd8e8j4u9uh4gxukaacckse64kx2l9dqv8rvrysdq5r5dt38t9snqj9u5ar07h2exr4fg56wpudkhkk7gtxlyt72ku5fpqqd4fnlk",
|
|
"payment_hash": "072b1d20f4a7c757a56d5fb10eaed40b58b68849da41fe396cdbd2d81692875a",
|
|
"amount_msat": 11000000,
|
|
"status": "unpaid",
|
|
"description": [
|
|
"XEoCR94SIz6UIRUEkxum."
|
|
],
|
|
"expires_at": 1706757730,
|
|
"created_index": 1
|
|
}
|
|
]
|
|
}
|
|
}
|
|
]
|
|
}
|