ListChannels

ListChannels returns a description of all the open channels that this node is a participant in.

Source: lightning.proto

gRPC

rpc ListChannels (ListChannelsRequest) returns (ListChannelsResponse);

REST

HTTP Method	Path
GET	/v1/channels

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 = {
  active_only: <bool>,
  inactive_only: <bool>,
  public_only: <bool>,
  private_only: <bool>,
  peer: <bytes>,
  peer_alias_lookup: <bool>,
};
client.listChannels(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "channels": <Channel>,
//  }

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.ListChannelsRequest(
  active_only=<bool>,
  inactive_only=<bool>,
  public_only=<bool>,
  private_only=<bool>,
  peer=<bytes>,
  peer_alias_lookup=<bool>,
)
response = stub.ListChannels(request)
print(response)
# {
#    "channels": <Channel>,
# }

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/channels`,
  // 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:
//  {
//    "channels": <array>, // <Channel> 
//  }

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/channels'
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())
# {
#    "channels": <Channel>,
# }

Shell

$ lncli listchannels --help

NAME:
   lncli listchannels - List all open channels.

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

CATEGORY:
   Channels

OPTIONS:
   --active_only             only list channels which are currently active
   --inactive_only           only list channels which are currently inactive
   --public_only             only list channels which are currently public
   --private_only            only list channels which are currently private
   --peer value              (optional) only display channels with a particular peer, accepts 66-byte, hex-encoded pubkeys
   --skip_peer_alias_lookup  skip the peer alias lookup per channel in order to improve performance
   

Messages

lnrpc.ListChannelsRequest

Source: lightning.proto

Field	gRPC Type	REST Type	REST Placement
active_only	bool	boolean	query
inactive_only	bool	boolean	query
public_only	bool	boolean	query
private_only	bool	boolean	query
peer Filters the response for channels with a target peer's pubkey. If peer is empty, all channels will be returned.	bytes	string	query
peer_alias_lookup Informs the server if the peer alias lookup per channel should be enabled. It is turned off by default in order to avoid degradation of performance for existing clients.	bool	boolean	query

lnrpc.ListChannelsResponse

Source: lightning.proto

Field	gRPC Type	REST Type
channels The list of active channels	Channel[]	array

Nested Messages

lnrpc.Channel

Field	gRPC Type	REST Type
active Whether this channel is active or not	bool	boolean
remote_pubkey The identity pubkey of the remote node	string	string
channel_point The outpoint (txid:index) of the funding transaction. With this value, Bob will be able to generate a signature for Alice's version of the commitment transaction.	string	string
chan_id The unique channel ID for the channel. The first 3 bytes are the block height, the next 3 the index within the block, and the last 2 bytes are the output index for the channel.	uint64	string
capacity The total amount of funds held in this channel	int64	string
local_balance This node's current balance in this channel	int64	string
remote_balance The counterparty's current balance in this channel	int64	string
commit_fee The amount calculated to be paid in fees for the current set of commitment transactions. The fee amount is persisted with the channel in order to allow the fee amount to be removed and recalculated with each channel state update, including updates that happen after a system restart.	int64	string
commit_weight The weight of the commitment transaction	int64	string
fee_per_kw The required number of satoshis per kilo-weight that the requester will pay at all times, for both the funding transaction and commitment transaction. This value can later be updated once the channel is open.	int64	string
unsettled_balance The unsettled balance in this channel	int64	string
total_satoshis_sent The total number of satoshis we've sent within this channel.	int64	string
total_satoshis_received The total number of satoshis we've received within this channel.	int64	string
num_updates The total number of updates conducted within this channel.	uint64	string
pending_htlcs The list of active, uncleared HTLCs currently pending within the channel.	HTLC[]	array
csv_delaydeprecated Deprecated. The CSV delay expressed in relative blocks. If the channel is force closed, we will need to wait for this many blocks before we can regain our funds.	uint32	integer
private Whether this channel is advertised to the network or not.	bool	boolean
initiator True if we were the ones that created the channel.	bool	boolean
chan_status_flags A set of flags showing the current state of the channel.	string	string
local_chan_reserve_satdeprecated Deprecated. The minimum satoshis this node is required to reserve in its balance.	int64	string
remote_chan_reserve_satdeprecated Deprecated. The minimum satoshis the other node is required to reserve in its balance.	int64	string
static_remote_keydeprecated Deprecated. Use commitment_type.	bool	boolean
commitment_type The commitment type used by this channel.	CommitmentType	string
lifetime The number of seconds that the channel has been monitored by the channel scoring system. Scores are currently not persisted, so this value may be less than the lifetime of the channel [EXPERIMENTAL].	int64	string
uptime The number of seconds that the remote peer has been observed as being online by the channel scoring system over the lifetime of the channel [EXPERIMENTAL].	int64	string
close_address Close address is the address that we will enforce payout to on cooperative close if the channel was opened utilizing option upfront shutdown. This value can be set on channel open by setting close_address in an open channel request. If this value is not set, you can still choose a payout address by cooperatively closing with the delivery_address field set.	string	string
push_amount_sat The amount that the initiator of the channel optionally pushed to the remote party on channel open. This amount will be zero if the channel initiator did not push any funds to the remote peer. If the initiator field is true, we pushed this amount to our peer, if it is false, the remote peer pushed this amount to us.	uint64	string
thaw_height This uint32 indicates if this channel is to be considered 'frozen'. A frozen channel doest not allow a cooperative channel close by the initiator. The thaw_height is the height that this restriction stops applying to the channel. This field is optional, not setting it or using a value of zero will mean the channel has no additional restrictions. The height can be interpreted in two ways: as a relative height if the value is less than 500,000, or as an absolute height otherwise.	uint32	integer
local_constraints List constraints for the local node.	ChannelConstraints	object
remote_constraints List constraints for the remote node.	ChannelConstraints	object
alias_scids This lists out the set of alias short channel ids that exist for a channel. This may be empty.	uint64[]	array
zero_conf Whether or not this is a zero-conf channel.	bool	boolean
zero_conf_confirmed_scid This is the confirmed / on-chain zero-conf SCID.	uint64	string
peer_alias The configured alias name of our peer.	string	string
peer_scid_alias This is the peer SCID alias.	uint64	string
memo An optional note-to-self to go along with the channel containing some useful information. This is only ever stored locally and in no way impacts the channel's operation.	string	string
custom_channel_data Custom channel data that might be populated in custom channels.	bytes	string

lnrpc.ChannelConstraints

Field	gRPC Type	REST Type
csv_delay The CSV delay expressed in relative blocks. If the channel is force closed, we will need to wait for this many blocks before we can regain our funds.	uint32	integer
chan_reserve_sat The minimum satoshis this node is required to reserve in its balance.	uint64	string
dust_limit_sat The dust limit (in satoshis) of the initiator's commitment tx.	uint64	string
max_pending_amt_msat The maximum amount of coins in millisatoshis that can be pending in this channel.	uint64	string
min_htlc_msat The smallest HTLC in millisatoshis that the initiator will accept.	uint64	string
max_accepted_htlcs The total number of incoming HTLC's that the initiator will accept.	uint32	integer

lnrpc.HTLC

Field	gRPC Type	REST Type
incoming	bool	boolean
amount	int64	string
hash_lock	bytes	string
expiration_height	uint32	integer
htlc_index Index identifying the htlc on the channel.	uint64	string
forwarding_channel If this HTLC is involved in a forwarding operation, this field indicates the forwarding channel. For an outgoing htlc, it is the incoming channel. For an incoming htlc, it is the outgoing channel. When the htlc originates from this node or this node is the final destination, forwarding_channel will be zero. The forwarding channel will also be zero for htlcs that need to be forwarded but don't have a forwarding decision persisted yet.	uint64	string
forwarding_htlc_index Index identifying the htlc on the forwarding channel.	uint64	string

Enums

lnrpc.CommitmentType

Name	Number
UNKNOWN_COMMITMENT_TYPE Returned when the commitment type isn't known or unavailable.	0
LEGACY A channel using the legacy commitment format having tweaked to_remote keys.	1
STATIC_REMOTE_KEY A channel that uses the modern commitment format where the key in the output of the remote party does not change each state. This makes back up and recovery easier as when the channel is closed, the funds go directly to that key.	2
ANCHORS A channel that uses a commitment format that has anchor outputs on the commitments, allowing fee bumping after a force close transaction has been broadcast.	3
SCRIPT_ENFORCED_LEASE A channel that uses a commitment type that builds upon the anchors commitment format, but in addition requires a CLTV clause to spend outputs paying to the channel initiator. This is intended for use on leased channels to guarantee that the channel initiator has no incentives to close a leased channel before its maturity date.	4
SIMPLE_TAPROOT A channel that uses musig2 for the funding output, and the new tapscript features where relevant.	5
SIMPLE_TAPROOT_OVERLAY Identical to the SIMPLE_TAPROOT channel type, but with extra functionality. This channel type also commits to additional meta data in the tapscript leaves for the scripts in a channel.	6