lightning-listforwards – Command showing all htlcs and their information


listforwards [status] [in_channel] [out_channel]


The listforwards RPC command displays all htlcs that have been attempted to be forwarded by the c-lightning node.

If status is specified, then only the forwards with the given status are returned. status can be either offered or settled or failed or local_failed

If in_channel or out_channel is specified, then only the matching forwards on the given in/out channel are returned.


On success one array will be returned: forwards with htlcs that have been processed

Each entry in forwards will include:

  • in_channel: the short_channel_id of the channel that recieved the incoming htlc.

  • in_msatoshi, in_msat - amount of msatoshis that are forwarded to this node.

  • status: status can be either offered if the routing process is still ongoing, settled if the routing process is completed or failed if the routing process could not be completed.

  • received_time: timestamp when incoming htlc was received.

The following additional fields are usually present, but will not be for some variants of status local_failed (if it failed before we determined these):

  • out_channel: the short_channel_id of to which the outgoing htlc is supposed to be forwarded.

  • fee, fee_msat: fee offered for forwarding the htlc in msatoshi.

  • out_msatoshi, out_msat - amount of msatoshis to be forwarded.

The following fields may be offered, but for old forgotten HTLCs they will be omitted:

  • payment_hash - the payment_hash belonging to the HTLC.

If the status is not ‘offered’, the following additional fields are present:

  • resolved_time - timestamp when htlc was resolved (settled or failed).


Rene Pickhardt <> is mainly responsible.




Main web site: