Skip to content
Tool for working with the balance of your satoshis on LND
Branch: master
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
arrays update dependencies Sep 1, 2019
balances add swap cost command Sep 10, 2019
chain add pay, peer, chain receive methods. standardize on kebab case args Aug 10, 2019
encryption update dependencies Sep 1, 2019
fiat add inbound and outbound restrictions to probes Aug 19, 2019
lnd update dependencies Sep 1, 2019
network add swap cost command Sep 10, 2019
responses add swap cost command Sep 10, 2019
routing add rebalance command Sep 2, 2019
swaps add swap cost command Sep 10, 2019
test end support for lnd 0.7.0 and lower Sep 20, 2019
wallets hide chain fees if chain fee reporting is absent Jul 24, 2019
.gitignore bump dependencies May 2, 2019
.tm_properties balance command Feb 11, 2019 end support for lnd 0.7.0 and lower Sep 20, 2019
LICENSE add swap cost command Sep 10, 2019
bos add swap cost command Sep 10, 2019
package-lock.json end support for lnd 0.7.0 and lower Sep 20, 2019
package.json end support for lnd 0.7.0 and lower Sep 20, 2019

Balance of Satoshis

Commands for working with lnd balances.


Requires Node v10.4.0+

npm install -g balanceofsatoshis

Verify it's installed:

bos --version
// current installed version


To see a list of available options and flags run:

bos help

// Or get individual help with a command
bos help commandName

Example Commands

# See an accounting formatted list of various types of transactions
bos accounting "category"

# Set autopilot on or off. With heuristic externalscore, set guided autopilot
bos autopilot "on"

# See total balance, including pending funds, excluding future commit fees
bos balance
# 1337

# See the current fee estimates confirmation targets
bos chainfees

# Receive funds via swap on-chain
bos chain-receive "amount"

# See details on how closed channels resolved on-chain
bos closed

# Create a utxo fan-out with on-chain funds
bos fanout "amount" "count"

# Query the node to find something like a payment, channel or node
bos find "query"

# Output a summarized version of peers forwarded towards
bos forwards

# Send a gift of some tokens to a directly connected peer
bos gift "pubkey" "amount"

# See help about a command
bos help "command"

# Output the sum total of remote channel liquidity
bos inbound-liquidity

# Increase inbound liquidity to the node
bos increase-inbound-liquidity

# Show liquidity adjustment costs
bos liquidity-cost "inbound" "amount"

# See market price history
bos market

# Outputs the sum total of local channel liquidity
bos outbound-liquidity

# Pay a payment request, probing first
bos pay "payment_request"

# Show channel-connected peers
bos peers

# Output the price of BTC
bos price

# Test if funds can be sent to a destination
bos probe "payment_request/public_key"

# Rebalance funds between peers
bos rebalance

# Get a general report of the node activity
bos report

# Unlock the wallet if it is locked
bos unlock "path_to_password_file"

# Show unspent coin outputs
bos utxos

Saved Nodes Directory

By default bos tries to locate tls.cert and admin.macaroon in the default lnd location on the local machine (~/.lnd/ on Linux, and ~/Library/Application Support/Lnd/ on MacOS).

It will check first for a mainnet macaroon, then a testnet macaroon.

To use bos with external nodes (or nodes with custom configuration), two things need to be done:

  1. Create directory ~/.bos/, and add node credentials in a format of:


  2. Each file should have the following format:

      "cert": "base64 tls.cert value",
      "macaroon": "base64 .macaroon value",
      "socket": "host:ip"

    Note: cert and (admin) macaroon should have base64-encoded, and newline-stripped content of the files. To get the strings in appropriate format you can run, ex:

    # For `cert` 
    base64 ~/.lnd/tls.cert | tr -d '\n'
    # For `macaroon`
    base64 ~/.lnd/data/chain/bitcoin/mainnet/admin.macaroon | tr -d '\n'

    Note_2: socket should contain host:ip pointing to lnd's gRPC interface, localhost:10009 by convention.

Using Saved Nodes

To run commands on nodes specified this way, you need to suffix commands with their name, ex:

bos balance --node=SAVED_NODE_NAME
bos forwards --node=SAVED_NODE_NAME

Linux Fu

Some commands are designed to return outputs that can be piped or used in other CLI programs.

Summarize Numbers

expr $(bos balance --node=savedNode1) + $(bos balance --node=savedNode1)
# outputs the combined balance of both nodes

Send Alerts

bos inbound-liquidity --below=1000000 2>&1 | sendnotification SNS "AWS_SNS_ID" "WARNING inbound-liquidity deficit: %s sats" --nonzero --subject="Low inbound liquidity warning: node1"
# sends email if the inbound liquidity drops below a 1,000,000 sats

Docker Usage

Potentially this can be used with Docker with a simple docker file

FROM node:latest
RUN npm install balanceofsatoshis
ENTRYPOINT [ "/node_modules/balanceofsatoshis/bos" ]
    #! /usr/bin/env bash
    docker run -it --rm -v=$HOME/.bos:/root/.bos bos:latest ${@:1}
You can’t perform that action at this time.