Info / Balances
Info / Balances
Understanding your Lightning node's status and current balances is a fundamental part of managing your liquidity. This page covers how to use LND's REST API to retrieve essential node information, as well as your on-chain and channel balances. These endpoints are crucial for monitoring the health of your node and managing your funds.
1. Get Basic Node Info
The /v1/getinfo endpoint provides a quick snapshot of your node's identity, synchronization status, and network connectivity. This is a common "health check" to ensure your LND instance is running and connected to the Bitcoin and Lightning networks.
The response includes your node's alias, current block height, version, and key statistics like the number of active channels and peers.
REST Endpoint
const getNodeInfo = async () => {
try {
const info = await lnd.get("/v1/getinfo");
return info.data;
} catch (error) {
console.error("Failed to get node info:", error);
throw error;
}
};2. Get On-Chain Balance
The /v1/balance/blockchain endpoint retrieves your on-chain Bitcoin balances managed by LND. This balance represents the funds in your node's Lightning wallet that are not yet committed to payment channels. This is an important metric for managing channel liquidity, as these funds can be used to open new channels.
The response provides a breakdown of your total balance, confirmed balance (funds available to spend), and unconfirmed balance (funds received but not yet confirmed on the blockchain).
REST Endpoint
const getOnChainBalance = async () => {
try {
const balance = await lnd.get("/v1/balance/blockchain");
return balance.data;
} catch (error) {
console.error("Failed to get on-chain balance:", error);
throw error;
}
};3. Get Channel Balances
The /v1/balance/channels endpoint provides a summary of all funds locked within your Lightning Network channels. This is your primary operating balance for sending and receiving Lightning payments.
The response will detail your local balance (funds you can send from your channels), your remote balance (funds you can receive from your channels), and the unsettled balance (funds pending confirmation from a channel update).
REST Endpoint
const getChannelBalances = async () => {
try {
const balance = await lnd.get("/v1/balance/channels");
return balance.data;
} catch (error) {
console.error("Failed to get channel balances:", error);
throw error;
}
};4. Get All Balances (Combined)
Often, you'll need a single, consolidated view of all your funds. By combining the three API calls above, you can create a complete balance overview for your application's dashboard.
This example function calls all three endpoints concurrently to fetch and format the full balance information in one go.
const getAllBalances = async () => {
try {
// Fetch all three pieces of data in parallel
const [
nodeInfo,
onChainBalance,
channelBalances
] = await Promise.all([
lnd.get("/v1/getinfo"),
lnd.get("/v1/balance/blockchain"),
lnd.get("/v1/balance/channels")
]);
// Format the combined data for easy use
const totalBalance = parseInt(onChainBalance.data.total_balance) + parseInt(channelBalances.data.local_balance);
return {
alias: nodeInfo.data.alias,
version: nodeInfo.data.version,
syncedToChain: nodeInfo.data.synced_to_chain,
blockHeight: nodeInfo.data.block_height,
onChain: {
total: onChainBalance.data.total_balance,
confirmed: onChainBalance.data.confirmed_balance,
unconfirmed: onChainBalance.data.unconfirmed_balance
},
channels: {
local: channelBalances.data.local_balance,
remote: channelBalances.data.remote_balance,
pending: channelBalances.data.pending_open_balance
},
totalBalance: totalBalance
};
} catch (error) {
console.error("Failed to get combined balances:", error);
throw error;
}
};
// Example usage
// getAllBalances().then(data => console.log(data));