WalletBalance

WalletBalance returns total unspent outputs(confirmed and unconfirmed), all confirmed unspent outputs and all unconfirmed unspent outputs under control of the wallet.

Source: lightning.proto

gRPC

rpc WalletBalance (WalletBalanceRequest) returns (WalletBalanceResponse);

REST

HTTP Method	Path
GET	/v1/balance/blockchain

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 = {
  account: <string>,
  min_confs: <int32>,
};
client.walletBalance(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "total_balance": <int64>,
//    "confirmed_balance": <int64>,
//    "unconfirmed_balance": <int64>,
//    "locked_balance": <int64>,
//    "reserved_balance_anchor_chan": <int64>,
//    "account_balance": <AccountBalanceEntry>,
//  }

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.WalletBalanceRequest(
  account=<string>,
  min_confs=<int32>,
)
response = stub.WalletBalance(request)
print(response)
# {
#    "total_balance": <int64>,
#    "confirmed_balance": <int64>,
#    "unconfirmed_balance": <int64>,
#    "locked_balance": <int64>,
#    "reserved_balance_anchor_chan": <int64>,
#    "account_balance": <AccountBalanceEntry>,
# }

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/blockchain`,
  // 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:
//  {
//    "total_balance": <string>, // <int64> 
//    "confirmed_balance": <string>, // <int64> 
//    "unconfirmed_balance": <string>, // <int64> 
//    "locked_balance": <string>, // <int64> 
//    "reserved_balance_anchor_chan": <string>, // <int64> 
//    "account_balance": <object>, // <AccountBalanceEntry> 
//  }

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/blockchain'
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())
# {
#    "total_balance": <int64>,
#    "confirmed_balance": <int64>,
#    "unconfirmed_balance": <int64>,
#    "locked_balance": <int64>,
#    "reserved_balance_anchor_chan": <int64>,
#    "account_balance": <AccountBalanceEntry>,
# }

Shell

$ lncli walletbalance --help

NAME:
   lncli walletbalance - Compute and display the wallet's current balance.

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

CATEGORY:
   Wallet

OPTIONS:
   --account value  (optional) the account for which the balance is shown
   

Messages

lnrpc.WalletBalanceRequest

Source: lightning.proto

Field	gRPC Type	REST Type	REST Placement
account The wallet account the balance is shown for. If this is not specified, the balance of the "default" account is shown.	string	string	query
min_confs The minimum number of confirmations each one of your outputs used for the funding transaction must satisfy. If this is not specified, the default value of 1 is used.	int32	integer	query

lnrpc.WalletBalanceResponse

Source: lightning.proto

Field	gRPC Type	REST Type
total_balance The balance of the wallet	int64	string
confirmed_balance The confirmed balance of a wallet(with >= 1 confirmations)	int64	string
unconfirmed_balance The unconfirmed balance of a wallet(with 0 confirmations)	int64	string
locked_balance The total amount of wallet UTXOs held in outputs that are locked for other usage.	int64	string
reserved_balance_anchor_chan The amount of reserve required.	int64	string
account_balance A mapping of each wallet account's name to its balance.	AccountBalanceEntry[]	object

Nested Messages

lnrpc.WalletAccountBalance

Field	gRPC Type	REST Type
confirmed_balance The confirmed balance of the account (with >= 1 confirmations).	int64	string
unconfirmed_balance The unconfirmed balance of the account (with 0 confirmations).	int64	string

lnrpc.WalletBalanceResponse.AccountBalanceEntry

Field	gRPC Type	REST Type
key	string	unknown
value	WalletAccountBalance	unknown