mirror of
https://github.com/ElementsProject/lightning.git
synced 2025-02-24 15:10:51 +01:00
453 lines
14 KiB
JSON
453 lines
14 KiB
JSON
{
|
|
"$schema": "../rpc-schema-draft.json",
|
|
"type": "object",
|
|
"rpc": "listsendpays",
|
|
"title": "Low-level command for querying sendpay status",
|
|
"description": [
|
|
"The **listsendpays** RPC command gets the status of all *sendpay* commands (which is also used by the *pay* command), or with *bolt11* or *payment_hash* limits results to that specific payment. You cannot specify both. It is possible to filter the payments also by *status*.",
|
|
"",
|
|
"Note that there may be more than one concurrent *sendpay* command per *pay*, so this command should be used with caution."
|
|
],
|
|
"categories": [
|
|
"readonly"
|
|
],
|
|
"request": {
|
|
"required": [],
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"bolt11": {
|
|
"type": "string",
|
|
"description": [
|
|
"Bolt11 invoice."
|
|
]
|
|
},
|
|
"payment_hash": {
|
|
"type": "hash",
|
|
"description": [
|
|
"The hash of the payment_preimage."
|
|
]
|
|
},
|
|
"status": {
|
|
"type": "string",
|
|
"enum": [
|
|
"pending",
|
|
"complete",
|
|
"failed"
|
|
],
|
|
"description": [
|
|
"Whether the invoice has been paid, pending, or failed."
|
|
]
|
|
},
|
|
"index": {
|
|
"type": "string",
|
|
"added": "v23.11",
|
|
"enum": [
|
|
"created",
|
|
"updated"
|
|
],
|
|
"description": [
|
|
"If neither bolt11 or payment_hash is specified, `index` controls ordering, by `created` (default) or `updated`."
|
|
]
|
|
},
|
|
"start": {
|
|
"type": "u64",
|
|
"added": "v23.11",
|
|
"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.11",
|
|
"description": [
|
|
"If `index` is specified, `limit` can be used to specify the maximum number of entries to return."
|
|
]
|
|
}
|
|
},
|
|
"dependentUpon": {
|
|
"index": [
|
|
"start",
|
|
"limit"
|
|
]
|
|
}
|
|
},
|
|
"response": {
|
|
"required": [
|
|
"payments"
|
|
],
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"payments": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"required": [
|
|
"id",
|
|
"created_index",
|
|
"payment_hash",
|
|
"status",
|
|
"groupid",
|
|
"created_at",
|
|
"amount_sent_msat"
|
|
],
|
|
"properties": {
|
|
"created_index": {
|
|
"added": "v23.11",
|
|
"type": "u64",
|
|
"description": [
|
|
"1-based index indicating order this payment was created in."
|
|
]
|
|
},
|
|
"id": {
|
|
"type": "u64",
|
|
"description": [
|
|
"Old synonym for created_index."
|
|
]
|
|
},
|
|
"groupid": {
|
|
"type": "u64",
|
|
"description": [
|
|
"Grouping key to disambiguate multiple attempts to pay an invoice or the same payment_hash."
|
|
]
|
|
},
|
|
"partid": {
|
|
"type": "u64",
|
|
"description": [
|
|
"Part number (for multiple parts to a single payment)."
|
|
]
|
|
},
|
|
"payment_hash": {
|
|
"type": "hash",
|
|
"description": [
|
|
"The hash of the *payment_preimage* which will prove payment."
|
|
]
|
|
},
|
|
"updated_index": {
|
|
"added": "v23.11",
|
|
"type": "u64",
|
|
"description": [
|
|
"1-based index indicating order this payment was changed (only present if it has changed since creation)."
|
|
]
|
|
},
|
|
"status": {
|
|
"type": "string",
|
|
"enum": [
|
|
"pending",
|
|
"failed",
|
|
"complete"
|
|
],
|
|
"description": [
|
|
"Status of the payment."
|
|
]
|
|
},
|
|
"amount_msat": {
|
|
"type": "msat",
|
|
"description": [
|
|
"The amount delivered to destination (if known)."
|
|
]
|
|
},
|
|
"destination": {
|
|
"type": "pubkey",
|
|
"description": [
|
|
"The final destination of the payment if known."
|
|
]
|
|
},
|
|
"created_at": {
|
|
"type": "u64",
|
|
"description": [
|
|
"The UNIX timestamp showing when this payment was initiated."
|
|
]
|
|
},
|
|
"amount_sent_msat": {
|
|
"type": "msat",
|
|
"description": [
|
|
"The amount sent."
|
|
]
|
|
},
|
|
"label": {
|
|
"type": "string",
|
|
"description": [
|
|
"The label, if given to sendpay."
|
|
]
|
|
},
|
|
"bolt11": {
|
|
"type": "string",
|
|
"description": [
|
|
"The bolt11 string (if pay supplied one)."
|
|
]
|
|
},
|
|
"description": {
|
|
"type": "string",
|
|
"description": [
|
|
"The description matching the bolt11 description hash (if pay supplied one)."
|
|
]
|
|
},
|
|
"bolt12": {
|
|
"type": "string",
|
|
"description": [
|
|
"The bolt12 string (if supplied for pay: **experimental-offers** only)."
|
|
]
|
|
}
|
|
},
|
|
"allOf": [
|
|
{
|
|
"if": {
|
|
"additionalProperties": true,
|
|
"properties": {
|
|
"status": {
|
|
"type": "string",
|
|
"enum": [
|
|
"complete"
|
|
]
|
|
}
|
|
}
|
|
},
|
|
"then": {
|
|
"additionalProperties": false,
|
|
"required": [
|
|
"payment_preimage"
|
|
],
|
|
"properties": {
|
|
"id": {},
|
|
"created_index": {},
|
|
"updated_index": {},
|
|
"partid": {},
|
|
"groupid": {},
|
|
"payment_hash": {},
|
|
"status": {},
|
|
"msatoshi": {},
|
|
"amount_msat": {},
|
|
"destination": {},
|
|
"created_at": {},
|
|
"msatoshi_sent": {},
|
|
"amount_sent_msat": {},
|
|
"label": {},
|
|
"bolt11": {},
|
|
"description": {},
|
|
"bolt12": {},
|
|
"completed_at": {
|
|
"type": "u64",
|
|
"added": "pre-v0.10.1",
|
|
"description": [
|
|
"The UNIX timestamp showing when this payment was completed."
|
|
]
|
|
},
|
|
"payment_preimage": {
|
|
"type": "secret",
|
|
"description": [
|
|
"The proof of payment: SHA256 of this **payment_hash**."
|
|
]
|
|
}
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"if": {
|
|
"additionalProperties": true,
|
|
"properties": {
|
|
"status": {
|
|
"type": "string",
|
|
"enum": [
|
|
"failed"
|
|
]
|
|
}
|
|
}
|
|
},
|
|
"then": {
|
|
"additionalProperties": false,
|
|
"required": [],
|
|
"properties": {
|
|
"id": {},
|
|
"created_index": {},
|
|
"updated_index": {},
|
|
"partid": {},
|
|
"groupid": {},
|
|
"payment_hash": {},
|
|
"status": {},
|
|
"msatoshi": {},
|
|
"amount_msat": {},
|
|
"destination": {},
|
|
"created_at": {},
|
|
"completed_at": {},
|
|
"msatoshi_sent": {},
|
|
"amount_sent_msat": {},
|
|
"label": {},
|
|
"bolt11": {},
|
|
"description": {},
|
|
"bolt12": {},
|
|
"erroronion": {
|
|
"type": "hex",
|
|
"description": [
|
|
"The onion message returned."
|
|
]
|
|
}
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"if": {
|
|
"additionalProperties": true,
|
|
"properties": {
|
|
"status": {
|
|
"type": "string",
|
|
"enum": [
|
|
"pending"
|
|
]
|
|
}
|
|
}
|
|
},
|
|
"then": {
|
|
"additionalProperties": false,
|
|
"required": [],
|
|
"properties": {
|
|
"id": {},
|
|
"created_index": {},
|
|
"updated_index": {},
|
|
"partid": {},
|
|
"groupid": {},
|
|
"payment_hash": {},
|
|
"status": {},
|
|
"msatoshi": {},
|
|
"amount_msat": {},
|
|
"destination": {},
|
|
"created_at": {},
|
|
"msatoshi_sent": {},
|
|
"amount_sent_msat": {},
|
|
"label": {},
|
|
"bolt11": {},
|
|
"description": {},
|
|
"bolt12": {}
|
|
}
|
|
}
|
|
}
|
|
]
|
|
}
|
|
}
|
|
},
|
|
"pre_return_value_notes": [
|
|
"Note that the returned array is ordered by increasing *id*."
|
|
]
|
|
},
|
|
"author": [
|
|
"Christian Decker <<decker.christian@gmail.com>> is mainly responsible."
|
|
],
|
|
"see_also": [
|
|
"lightning-listpays(7)",
|
|
"lightning-sendpay(7)",
|
|
"lightning-listinvoices(7)"
|
|
],
|
|
"resources": [
|
|
"Main web site: <https://github.com/ElementsProject/lightning>"
|
|
],
|
|
"examples": [
|
|
{
|
|
"request": {
|
|
"id": "example:listsendpays#1",
|
|
"method": "listsendpays",
|
|
"params": {
|
|
"bolt11": "lnbcrt100n1pnt2bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000"
|
|
}
|
|
},
|
|
"response": {
|
|
"payments": [
|
|
{
|
|
"created_index": 2,
|
|
"id": 2,
|
|
"payment_hash": "paymenthashinvl0310031003100310031003100310031003100310031003100",
|
|
"groupid": 1,
|
|
"updated_index": 2,
|
|
"destination": "nodeid030303030303030303030303030303030303030303030303030303030303",
|
|
"amount_msat": 10000,
|
|
"amount_sent_msat": 10001,
|
|
"created_at": 1738000000,
|
|
"completed_at": 1739000000,
|
|
"status": "complete",
|
|
"payment_preimage": "paymentpreimagew010101010101010101010101010101010101010101010101"
|
|
}
|
|
]
|
|
}
|
|
},
|
|
{
|
|
"request": {
|
|
"id": "example:listsendpays#2",
|
|
"method": "listsendpays",
|
|
"params": {}
|
|
},
|
|
"response": {
|
|
"payments": [
|
|
{
|
|
"created_index": 2,
|
|
"id": 2,
|
|
"payment_hash": "paymenthashinvl0310031003100310031003100310031003100310031003100",
|
|
"groupid": 1,
|
|
"updated_index": 2,
|
|
"destination": "nodeid030303030303030303030303030303030303030303030303030303030303",
|
|
"amount_msat": 10000,
|
|
"amount_sent_msat": 10001,
|
|
"created_at": 1738000000,
|
|
"completed_at": 1739000000,
|
|
"status": "complete",
|
|
"payment_preimage": "paymentpreimagew010101010101010101010101010101010101010101010101"
|
|
},
|
|
{
|
|
"created_index": 3,
|
|
"id": 3,
|
|
"payment_hash": "paymenthashkey01k101k101k101k101k101k101k101k101k101k101k101k101",
|
|
"groupid": 0,
|
|
"updated_index": 3,
|
|
"destination": "nodeid030303030303030303030303030303030303030303030303030303030303",
|
|
"amount_msat": 10000,
|
|
"amount_sent_msat": 10001,
|
|
"created_at": 1738010000,
|
|
"completed_at": 1739010000,
|
|
"status": "complete",
|
|
"payment_preimage": "paymentpreimage1010101010101010101010101010101010101010101010101"
|
|
},
|
|
{
|
|
"created_index": 4,
|
|
"id": 4,
|
|
"payment_hash": "paymenthashkey02k201k201k201k201k201k201k201k201k201k201k201k201",
|
|
"groupid": 0,
|
|
"updated_index": 4,
|
|
"destination": "nodeid040404040404040404040404040404040404040404040404040404040404",
|
|
"amount_msat": 10000000,
|
|
"amount_sent_msat": 10000202,
|
|
"created_at": 1738020000,
|
|
"completed_at": 1739020000,
|
|
"status": "complete",
|
|
"payment_preimage": "paymentpreimage2020202020202020202020202020202020202020202020202"
|
|
},
|
|
{
|
|
"created_index": 5,
|
|
"id": 5,
|
|
"payment_hash": "paymenthashkey03k301k301k301k301k301k301k301k301k301k301k301k301",
|
|
"groupid": 0,
|
|
"updated_index": 5,
|
|
"destination": "nodeid030303030303030303030303030303030303030303030303030303030303",
|
|
"amount_msat": 10000,
|
|
"amount_sent_msat": 10001,
|
|
"created_at": 1738030000,
|
|
"completed_at": 1739030000,
|
|
"status": "failed"
|
|
},
|
|
{
|
|
"created_index": 6,
|
|
"id": 6,
|
|
"payment_hash": "paymenthashkey03k301k301k301k301k301k301k301k301k301k301k301k301",
|
|
"groupid": 0,
|
|
"updated_index": 6,
|
|
"partid": 1,
|
|
"destination": "nodeid030303030303030303030303030303030303030303030303030303030303",
|
|
"amount_msat": 10000,
|
|
"amount_sent_msat": 10001,
|
|
"created_at": 1738040000,
|
|
"completed_at": 1739040000,
|
|
"status": "complete",
|
|
"payment_preimage": "paymentpreimage3030303030303030303030303030303030303030303030303"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
]
|
|
}
|