ChannelBalance

ChannelBalance returns a report on the total funds across all open channels, categorized in local/remote, pending local/remote and unsettled local/remote balances.

Source: lightning.proto

gRPC

rpc ChannelBalance (ChannelBalanceRequest) returns (ChannelBalanceResponse);

REST

HTTP Method	Path
GET	/v1/balance/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 = {};
client.channelBalance(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "balance": <int64>,
//    "pending_open_balance": <int64>,
//    "local_balance": <Amount>,
//    "remote_balance": <Amount>,
//    "unsettled_local_balance": <Amount>,
//    "unsettled_remote_balance": <Amount>,
//    "pending_open_local_balance": <Amount>,
//    "pending_open_remote_balance": <Amount>,
//    "custom_channel_data": <bytes>,
//  }

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.ChannelBalanceRequest()
response = stub.ChannelBalance(request)
print(response)
# {
#    "balance": <int64>,
#    "pending_open_balance": <int64>,
#    "local_balance": <Amount>,
#    "remote_balance": <Amount>,
#    "unsettled_local_balance": <Amount>,
#    "unsettled_remote_balance": <Amount>,
#    "pending_open_local_balance": <Amount>,
#    "pending_open_remote_balance": <Amount>,
#    "custom_channel_data": <bytes>,
# }

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/balance/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:
//  {
//    "balance": <string>, // <int64> 
//    "pending_open_balance": <string>, // <int64> 
//    "local_balance": <object>, // <Amount> 
//    "remote_balance": <object>, // <Amount> 
//    "unsettled_local_balance": <object>, // <Amount> 
//    "unsettled_remote_balance": <object>, // <Amount> 
//    "pending_open_local_balance": <object>, // <Amount> 
//    "pending_open_remote_balance": <object>, // <Amount> 
//    "custom_channel_data": <string>, // <bytes> 
//  }

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/balance/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())
# {
#    "balance": <int64>,
#    "pending_open_balance": <int64>,
#    "local_balance": <Amount>,
#    "remote_balance": <Amount>,
#    "unsettled_local_balance": <Amount>,
#    "unsettled_remote_balance": <Amount>,
#    "pending_open_local_balance": <Amount>,
#    "pending_open_remote_balance": <Amount>,
#    "custom_channel_data": <bytes>,
# }

Shell

$ lncli channelbalance --help

NAME:
   lncli channelbalance - Returns the sum of the total available channel balance across all open channels.

USAGE:
   lncli channelbalance [arguments...]

CATEGORY:
   Channels

Messages

lnrpc.ChannelBalanceRequest

Source: lightning.proto

note

This request has no parameters.

lnrpc.ChannelBalanceResponse

Source: lightning.proto

Field	gRPC Type	REST Type
balancedeprecated Deprecated. Sum of channels balances denominated in satoshis	int64	string
pending_open_balancedeprecated Deprecated. Sum of channels pending balances denominated in satoshis	int64	string
local_balance Sum of channels local balances.	Amount	object
remote_balance Sum of channels remote balances.	Amount	object
unsettled_local_balance Sum of channels local unsettled balances.	Amount	object
unsettled_remote_balance Sum of channels remote unsettled balances.	Amount	object
pending_open_local_balance Sum of channels pending local balances.	Amount	object
pending_open_remote_balance Sum of channels pending remote balances.	Amount	object
custom_channel_data Custom channel data that might be populated if there are custom channels present.	bytes	string

Nested Messages

lnrpc.Amount

Field	gRPC Type	REST Type
sat Value denominated in satoshis.	uint64	string
msat Value denominated in milli-satoshis.	uint64	string