ListPeers

ListPeers returns a verbose listing of all currently active peers.

Source: lightning.proto

gRPC

rpc ListPeers (ListPeersRequest) returns (ListPeersResponse);

REST

HTTP Method	Path
GET	/v1/peers

Code Samples

gRPC

Javascript

const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');

const GRPC_HOST = 'localhost:10009'
const MACAROON_PATH = 'LND_DIR/data/chain/bitcoin/regtest/admin.macaroon'
const TLS_PATH = 'LND_DIR/tls.cert'

const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true,
};
const packageDefinition = protoLoader.loadSync('lightning.proto', loaderOptions);
const lnrpc = grpc.loadPackageDefinition(packageDefinition).lnrpc;
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const tlsCert = fs.readFileSync(TLS_PATH);
const sslCreds = grpc.credentials.createSsl(tlsCert);
const macaroon = fs.readFileSync(MACAROON_PATH).toString('hex');
const macaroonCreds = grpc.credentials.createFromMetadataGenerator(function(args, callback) {
  let metadata = new grpc.Metadata();
  metadata.add('macaroon', macaroon);
  callback(null, metadata);
});
let creds = grpc.credentials.combineChannelCredentials(sslCreds, macaroonCreds);
let client = new lnrpc.Lightning(GRPC_HOST, creds);
let request = {
  latest_error: <bool>,
};
client.listPeers(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "peers": <Peer>,
//  }

Python

import codecs, grpc, os
# Generate the following 2 modules by compiling the lightning.proto with the grpcio-tools.
# See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
import lightning_pb2 as lnrpc, lightning_pb2_grpc as lightningstub

GRPC_HOST = 'localhost:10009'
MACAROON_PATH = 'LND_DIR/data/chain/bitcoin/regtest/admin.macaroon'
TLS_PATH = 'LND_DIR/tls.cert'

# create macaroon credentials
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
def metadata_callback(context, callback):
  callback([('macaroon', macaroon)], None)
auth_creds = grpc.metadata_call_credentials(metadata_callback)
# create SSL credentials
os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
cert = open(TLS_PATH, 'rb').read()
ssl_creds = grpc.ssl_channel_credentials(cert)
# combine macaroon and SSL credentials
combined_creds = grpc.composite_channel_credentials(ssl_creds, auth_creds)
# make the request
channel = grpc.secure_channel(GRPC_HOST, combined_creds)
stub = lightningstub.LightningStub(channel)
request = lnrpc.ListPeersRequest(
  latest_error=<bool>,
)
response = stub.ListPeers(request)
print(response)
# {
#    "peers": <Peer>,
# }

REST

Javascript

const fs = require('fs');
const request = require('request');

const REST_HOST = 'localhost:8080'
const MACAROON_PATH = 'LND_DIR/data/chain/bitcoin/regtest/admin.macaroon'

let options = {
  url: `https://${REST_HOST}/v1/peers`,
  // Work-around for self-signed certificates.
  rejectUnauthorized: false,
  json: true,
  headers: {
    'Grpc-Metadata-macaroon': fs.readFileSync(MACAROON_PATH).toString('hex'),
  },
}
request.get(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  {
//    "peers": <array>, // <Peer> 
//  }

Python

import base64, codecs, json, requests

REST_HOST = 'localhost:8080'
MACAROON_PATH = 'LND_DIR/data/chain/bitcoin/regtest/admin.macaroon'
TLS_PATH = 'LND_DIR/tls.cert'

url = f'https://{REST_HOST}/v1/peers'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
r = requests.get(url, headers=headers, verify=TLS_PATH)
print(r.json())
# {
#    "peers": <Peer>,
# }

Shell

$ lncli listpeers --help

NAME:
   lncli listpeers - List all active, currently connected peers.

USAGE:
   lncli listpeers [command options] [arguments...]

CATEGORY:
   Peers

OPTIONS:
   --list_errors  list a full set of most recent errors for the peer
   

Messages

lnrpc.ListPeersRequest

Source: lightning.proto

Field	gRPC Type	REST Type	REST Placement
latest_error If true, only the last error that our peer sent us will be returned with the peer's information, rather than the full set of historic errors we have stored.	bool	boolean	query

lnrpc.ListPeersResponse

Source: lightning.proto

Field	gRPC Type	REST Type
peers The list of currently connected peers	Peer[]	array

Nested Messages

lnrpc.Peer

Field	gRPC Type	REST Type
pub_key The identity pubkey of the peer	string	string
address Network address of the peer; eg `127.0.0.1:10011`	string	string
bytes_sent Bytes of data transmitted to this peer	uint64	string
bytes_recv Bytes of data transmitted from this peer	uint64	string
sat_sent Satoshis sent to this peer	int64	string
sat_recv Satoshis received from this peer	int64	string
inbound A channel is inbound if the counterparty initiated the channel	bool	boolean
ping_time Ping time to this peer	int64	string
sync_type The type of sync we are currently performing with this peer.	SyncType	string
features Features advertised by the remote peer in their init message.	FeaturesEntry[]	object
errors The latest errors received from our peer with timestamps, limited to the 10 most recent errors. These errors are tracked across peer connections, but are not persisted across lnd restarts. Note that these errors are only stored for peers that we have channels open with, to prevent peers from spamming us with errors at no cost.	TimestampedError[]	array
flap_count The number of times we have recorded this peer going offline or coming online, recorded across restarts. Note that this value is decreased over time if the peer has not recently flapped, so that we can forgive peers with historically high flap counts.	int32	integer
last_flap_ns The timestamp of the last flap we observed for this peer. If this value is zero, we have not observed any flaps for this peer.	int64	string
last_ping_payload The last ping payload the peer has sent to us.	bytes	string

lnrpc.Peer.FeaturesEntry

Field	gRPC Type	REST Type
key	uint32	unknown
value	Feature	unknown

lnrpc.Feature

Field	gRPC Type	REST Type
name	string	string
is_required	bool	boolean
is_known	bool	boolean

lnrpc.TimestampedError

Field	gRPC Type	REST Type
timestamp The unix timestamp in seconds when the error occurred.	uint64	string
error The string representation of the error sent by our peer.	string	string

Enums

lnrpc.Peer.SyncType

Name	Number
UNKNOWN_SYNC Denotes that we cannot determine the peer's current sync type.	0
ACTIVE_SYNC Denotes that we are actively receiving new graph updates from the peer.	1
PASSIVE_SYNC Denotes that we are not receiving new graph updates from the peer.	2
PINNED_SYNC Denotes that this peer is pinned into an active sync.	3