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

NAME
     listpeers -- Command returning data on connected lightning nodes

SYNOPSIS
     listpeers [id] [level]

DESCRIPTION
     The  listpeers  RPC command returns data on nodes that are connected or are
     not connected but have open channels with this node.

     Once a connection to another lightning node has been established, using the
     connect command, data on the node can be returned using listpeers	and  the
     id that was used with the connect command.

     If  no id is supplied, then data on all lightning nodes that are connected,
     or not connected but have open channels with this node, are returned.

     If a channel is open with a node and the connection has been lost, then the
     node will still appear in the output of the command and the  value  of  the
     connected attribute of the node will be "false".

     The  channel  will remain open for a set blocktime, after which if the con-
     nection has not been re-established, the channel will close  and  the  node
     will no longer appear in the command output.

     *	id  (pubkey,  optional): If supplied, limits the result to just the peer
	with the given ID, if it exists.
     *	level (string, optional) (one of "io", "trace",  "debug",  "info",  "un-
	usual"):  Supplying  level will show log entries related to that peer at
	the given log level.

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

     *	id (pubkey): The unique id of the peer.
     *	connected (boolean): Value showing the connection status.
     *	num_channels  (u32): The number of channels the peer has with this node.
	(added v23.02)
     *	log (array of objects, optional): If level is specified, logs  for  this
	peer.:
	*  type  (string)  (one  of "SKIPPED", "BROKEN", "UNUSUAL", "INFO", "DE-
	   BUG", "TRACE", "IO_IN", "IO_OUT")

	If type is "SKIPPED": - num_skipped (u32): Number of deleted/omitted en-
	tries.

	If type is "BROKEN", "UNUSUAL",  "INFO",  "DEBUG"  or  "TRACE":  -  time
	(string):  UNIX timestamp with 9 decimal places.  - source (string): The
	particular logbook this was found in.  - log (string):	The  actual  log
	message.  - node_id (pubkey): The peer this is associated with.

	If  type  is "IO_IN" or "IO_OUT": - time (string): UNIX timestamp with 9
	decimal places.  - source (string):  The  particular  logbook  this  was
	found  in.  - log (string): The actual log message.  - node_id (pubkey):
	The peer this is associated with.  - data (hex): The IO which occurred.

     If connected is true: - netaddr (array of strings): A single entry  array.:
     - (string, optional): Address, e.g. 1.2.3.4:1234.	- features (hex): Bitmap
     of  BOLT  #9 features from peer's INIT message.  - remote_addr (string, op-
     tional):  The  public  IPv4/6  address  the  peer	sees   us   from,   e.g.
     1.2.3.4:1234.

ERRORS
     On error the returned object will contain code and message properties, with
     code being one of the following:

     *	-32602: If the given parameters are wrong.

AUTHOR
     Michael Hawkins michael.hawkins@protonmail.com.

SEE ALSO
     lightning-connect(7),   lightning-fundchannel_start(7),  lightning-setchan-
     nel(7)

RESOURCES
     Main web site: https://github.com/ElementsProject/lightning  Lightning  RFC
     site   (BOLT   #9):  https://github.com/lightning/bolts/blob/master/09-fea-
     tures.md

EXAMPLES
     Example 1:

     Request:

     $ lightning-cli listpeers -k "id"="nodeid030303030303030303030303030303030303030303030303030303030303"

     {
       "id": "example:listpeers#1",
       "method": "listpeers",
       "params": {
	 "id": "nodeid030303030303030303030303030303030303030303030303030303030303"
       }
     }

     Response:

     {
       "peers": [
	 {
	   "id": "nodeid030303030303030303030303030303030303030303030303030303030303",
	   "connected": true,
	   "num_channels": 1,
	   "netaddr": [
	     "127.0.0.1:19736"
	   ],
	   "features": "0898882a8a59a1"
	 }
       ]
     }

     Example 2:

     Request:

     $ lightning-cli listpeers

     {
       "id": "example:listpeers#2",
       "method": "listpeers",
       "params": {}
     }

     Response:

     {
       "peers": [
	 {
	   "id": "nodeid010101010101010101010101010101010101010101010101010101010101",
	   "connected": true,
	   "num_channels": 1,
	   "netaddr": [
	     "127.0.0.1:19734"
	   ],
	   "features": "0898882a8a59a1"
	 },
	 {
	   "id": "nodeid030303030303030303030303030303030303030303030303030303030303",
	   "connected": true,
	   "num_channels": 1,
	   "netaddr": [
	     "127.0.0.1:19736"
	   ],
	   "features": "0898882a8a59a1"
	 },
	 {
	   "id": "nodeid040404040404040404040404040404040404040404040404040404040404",
	   "connected": false,
	   "num_channels": 1,
	   "features": "0898882a8a59a1"
	 }
       ]
     }

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