LIGHTNING-LISTFORWARDS(7) LIGHTNING-LISTFORWARDS(7) NAME listforwards -- Command showing all htlcs and their information SYNOPSIS listforwards [status] [in_channel] [out_channel] [index [start] [limit]] DESCRIPTION The listforwards RPC command displays all htlcs that have been attempted to be forwarded by the Core Lightning node. * status (string, optional) (one of "offered", "settled", "local_failed", "failed"): If specified, then only the forwards with the given status are returned. * in_channel (short_channel_id, optional): Only the matching forwards on the given inbound channel are returned. * out_channel (short_channel_id, optional): Only the matching forwards on the given outbount channel are returned. * index (string, optional) (one of "created", "updated"): If neither in_channel nor out_channel is specified, it controls ordering. The de- fault is created. (added v23.11) * start (u64, optional): If index is specified, start may be specified to start from that value, which is generally returned from lightning- wait(7). (added v23.11) * limit (u32, optional): If index is specified, limit can be used to spec- ify the maximum number of entries to return. (added v23.11) RETURN VALUE On success, an object containing forwards is returned. It is an array of objects, where each object contains: * created_index (u64): 1-based index indicating order this forward was created in. (added v23.11) * in_channel (short_channel_id): The channel that received the HTLC. * in_msat (msat): The value of the incoming HTLC. * status (string) (one of "offered", "settled", "local_failed", "failed"): Still ongoing, completed, failed locally, or failed after forwarding. * received_time (number): The UNIX timestamp when this was received (may be zero for old forwards). * in_htlc_id (u64, optional): The unique HTLC id the sender gave this (not present if incoming channel was closed before upgrade to v22.11). * out_channel (short_channel_id, optional): The channel that the HTLC (trying to) forward to. * out_htlc_id (u64, optional): The unique HTLC id we gave this when send- ing (may be missing even if out_channel is present, for old forwards be- fore v22.11). * updated_index (u64, optional): 1-based index indicating order this for- ward was changed (only present if it has changed since creation). (added v23.11) * style (string, optional) (one of "legacy", "tlv"): Either a legacy onion format or a modern tlv format. If out_msat is present: - fee_msat (msat): The amount this paid in fees. - out_msat (msat): The amount we sent out the out_channel. If status is "settled" or "failed": - resolved_time (number): The UNIX timestamp when this was resolved. If status is "local_failed" or "failed": - failcode (u32, optional): The numeric onion code returned. - failreason (string, optional): The name of the onion code returned. AUTHOR Rene Pickhardt r.pickhardt@gmail.com is mainly responsible. SEE ALSO lightning-autoclean-status(7), lightning-getinfo(7) RESOURCES Main web site: https://github.com/ElementsProject/lightning EXAMPLES Example 1: Request: $ lightning-cli listforwards -k "in_channel"="109x1x1" "out_channel"="123x1x1" "status"="settled" { "id": "example:listforwards#1", "method": "listforwards", "params": { "in_channel": "109x1x1", "out_channel": "123x1x1", "status": "settled" } } Response: { "forwards": [ { "created_index": 12, "updated_index": 7, "in_channel": "109x1x1", "in_htlc_id": 19, "out_channel": "123x1x1", "out_htlc_id": 2, "in_msat": 50000501, "out_msat": 50000000, "fee_msat": 501, "status": "settled", "style": "tlv", "received_time": 1738000000, "resolved_time": 1738500000 }, { "created_index": 13, "updated_index": 8, "in_channel": "109x1x1", "in_htlc_id": 20, "out_channel": "123x1x1", "out_htlc_id": 3, "in_msat": 50000501, "out_msat": 50000000, "fee_msat": 501, "status": "settled", "style": "tlv", "received_time": 1738010000, "resolved_time": 1738510000 } ] } Example 2: Request: $ lightning-cli listforwards { "id": "example:listforwards#2", "method": "listforwards", "params": {} } Response: { "forwards": [ { "created_index": 1, "updated_index": 1, "in_channel": "109x1x1", "in_htlc_id": 1, "out_channel": "111x1x1", "out_htlc_id": 1, "in_msat": 10001, "out_msat": 10000, "fee_msat": 1, "status": "settled", "style": "tlv", "received_time": 1738000000, "resolved_time": 1738500000 }, { "created_index": 2, "updated_index": 2, "in_channel": "109x1x1", "in_htlc_id": 2, "out_channel": "111x1x1", "out_htlc_id": 2, "in_msat": 10001, "out_msat": 10000, "fee_msat": 1, "status": "settled", "style": "tlv", "received_time": 1738010000, "resolved_time": 1738510000 }, { "created_index": 3, "updated_index": 3, "in_channel": "109x1x1", "in_htlc_id": 3, "out_channel": "111x1x1", "out_htlc_id": 3, "in_msat": 10000202, "out_msat": 10000101, "fee_msat": 101, "status": "settled", "style": "tlv", "received_time": 1738020000, "resolved_time": 1738520000 }, { "created_index": 5, "updated_index": 4, "in_channel": "109x1x1", "in_htlc_id": 5, "out_channel": "111x1x1", "out_htlc_id": 4, "in_msat": 10001, "out_msat": 10000, "fee_msat": 1, "status": "settled", "style": "tlv", "received_time": 1738030000, "resolved_time": 1738530000 }, { "created_index": 6, "updated_index": 5, "in_channel": "109x1x1", "in_htlc_id": 6, "out_channel": "111x1x1", "out_htlc_id": 5, "in_msat": 50001, "out_msat": 50000, "fee_msat": 1, "status": "settled", "style": "tlv", "received_time": 1738040000, "resolved_time": 1738540000 } ] } Core Lightning v26.06.1 LIGHTNING-LISTFORWARDS(7)
NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | AUTHOR | SEE ALSO | RESOURCES | EXAMPLES
Want to link to this manual page? Use this URL:
<https://man.FreeBSD.org/cgi/man.cgi?query=lightning-listforwards&sektion=7&manpath=FreeBSD+Ports+15.1.quarterly>