home | help 
LIGHTNING-LISTHTLCS(7)					  LIGHTNING-LISTHTLCS(7)

NAME
     listhtlcs -- Command for querying HTLCs

SYNOPSIS
     listhtlcs [id] [index] [start] [limit]

DESCRIPTION
     Command added in v22.11.

     The listhtlcs RPC command gets all HTLCs (which, generally, we remember for
     as long as a channel is open, even if they've completed long ago).

     *	id  (string,  optional): A short channel id (e.g. 1x2x3) or full 64-byte
	hex channel id, it will only list htlcs for that channel (which must  be
	known).
     *	index  (string,  optional)  (one of "created", "updated"): This controls
	the ordering of results. The default is created. (added v25.05)
     *	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 v25.05)
     *	limit (u32, optional): If index is specified, limit can be used to spec-
	ify the maximum number of entries to return. (added v25.05)

RETURN VALUE
     On success, an object containing htlcs is returned. It is an array  of  ob-
     jects, where each object contains:

     *	short_channel_id (short_channel_id): The channel that contains/contained
	the HTLC.
     *	created_index  (u64):  1-based index indicating order this htlc was cre-
	ated in. (added v25.05)
     *	id (u64): The unique, incrementing HTLC id the creator gave this.
     *	expiry (u32): The block number where this HTLC expires/expired.
     *	amount_msat (msat): The value of the HTLC.
     *	direction (string) (one of "out", "in"): Out if we offered this  to  the
	peer, in if they offered it.
     *	payment_hash (hash): Payment hash sought by HTLC.
     *	state (string) (one of "SENT_ADD_HTLC", "SENT_ADD_COMMIT", "RCVD_ADD_RE-
	VOCATION",  "RCVD_ADD_ACK_COMMIT",  "SENT_ADD_ACK_REVOCATION", "RCVD_RE-
	MOVE_HTLC",  "RCVD_REMOVE_COMMIT",  "SENT_REMOVE_REVOCATION",  "SENT_RE-
	MOVE_ACK_COMMIT",     "RCVD_REMOVE_ACK_REVOCATION",	"RCVD_ADD_HTLC",
	"RCVD_ADD_COMMIT",     "SENT_ADD_REVOCATION",	  "SENT_ADD_ACK_COMMIT",
	"RCVD_ADD_ACK_REVOCATION",   "SENT_REMOVE_HTLC",   "SENT_REMOVE_COMMIT",
	"RCVD_REMOVE_REVOCATION", "RCVD_REMOVE_ACK_COMMIT", "SENT_REMOVE_ACK_RE-
	VOCATION"): The first 10 states are for out, the next 10 are for in.
     *	updated_index (u64, optional): 1-based index indicating order this  htlc
	was  changed  (only  present  if  it has changed since creation). (added
	v25.05)

AUTHOR
     Rusty Russell rusty@rustcorp.com.au is mainly responsible.

SEE ALSO
     lightning-listforwards(7)

RESOURCES
     Main web site: https://github.com/ElementsProject/lightning

EXAMPLES
     Example 1:

     Request:

     $ lightning-cli listhtlcs "109x1x1"

     {
       "id": "example:listhtlcs#1",
       "method": "listhtlcs",
       "params": [
	 "109x1x1"
       ]
     }

     Response:

     {
       "htlcs": [
	 {
	   "created_index": 1,
	   "updated_index": 9,
	   "short_channel_id": "109x1x1",
	   "id": 0,
	   "expiry": 126,
	   "direction": "out",
	   "amount_msat": 500000000,
	   "payment_hash": "paymenthashdelpay10101010101010101010101010101010101010101010101",
	   "state": "RCVD_REMOVE_ACK_REVOCATION"
	 },
	 {
	   "created_index": 2,
	   "updated_index": 18,
	   "short_channel_id": "109x1x1",
	   "id": 1,
	   "expiry": 135,
	   "direction": "out",
	   "amount_msat": 10001,
	   "payment_hash": "paymenthashinvl0310031003100310031003100310031003100310031003100",
	   "state": "RCVD_REMOVE_ACK_REVOCATION"
	 },
	 {
	   "created_index": 3,
	   "updated_index": 27,
	   "short_channel_id": "109x1x1",
	   "id": 2,
	   "expiry": 149,
	   "direction": "out",
	   "amount_msat": 10001,
	   "payment_hash": "paymenthashkey01k101k101k101k101k101k101k101k101k101k101k101k101",
	   "state": "RCVD_REMOVE_ACK_REVOCATION"
	 },
	 {
	   "created_index": 4,
	   "updated_index": 36,
	   "short_channel_id": "109x1x1",
	   "id": 3,
	   "expiry": 155,
	   "direction": "out",
	   "amount_msat": 10000202,
	   "payment_hash": "paymenthashkey02k201k201k201k201k201k201k201k201k201k201k201k201",
	   "state": "RCVD_REMOVE_ACK_REVOCATION"
	 },
	 {
	   "created_index": 5,
	   "updated_index": 44,
	   "short_channel_id": "109x1x1",
	   "id": 4,
	   "expiry": 152,
	   "direction": "out",
	   "amount_msat": 10001,
	   "payment_hash": "paymenthashkey03k301k301k301k301k301k301k301k301k301k301k301k301",
	   "state": "RCVD_REMOVE_ACK_REVOCATION"
	 }
       ]
     }

     Example 2:

     Request:

     $ lightning-cli listhtlcs -k "index"="created" "start"=4 "limit"=1

     {
       "id": "example:listhtlcs#2",
       "method": "listhtlcs",
       "params": {
	 "index": "created",
	 "start": 4,
	 "limit": 1
       }
     }

     Response:

     {
       "htlcs": [
	 {
	   "created_index": 4,
	   "updated_index": 36,
	   "short_channel_id": "109x1x1",
	   "id": 3,
	   "expiry": 155,
	   "direction": "out",
	   "amount_msat": 10000202,
	   "payment_hash": "paymenthashkey02k201k201k201k201k201k201k201k201k201k201k201k201",
	   "state": "RCVD_REMOVE_ACK_REVOCATION"
	 }
       ]
     }

Core Lightning v26.06.1 				  LIGHTNING-LISTHTLCS(7)
home | help