Balance of Satoshis

Commands for working with LND balances.

Supported LND versions:

v0.20.0-beta to v0.20.1-beta
v0.19.0-beta to v0.19.3-beta
v0.18.0-beta to v0.18.5-beta
v0.17.0-beta to v0.17.5-beta
v0.16.0-beta to v0.16.4-beta
v0.15.2-beta to v0.15.5-beta

Install

Requires an [installation of Node v20+][nodejs-install-guide]

npm install -g balanceofsatoshis

Or use a platform-specific guide:

Docker/BTCPayServer install notes
[RaspiBlitz install guide][raspiblitz-install-guide]
[RaspiBolt/Debian guide][raspibolt-install-guide]
[Umbrel install guide][umbrel-install-guide]

If you want to try out any command without npm install, you can also do npx balanceofsatoshis to run a command directly.

Get the version to verify that it's installed:

bos --version
# current installed version

Re-install if you want to update to a new version.

Usage

To see a list of available options and flags run:

bos help

# Or get individual help with a command
bos help commandName

Community

Use bos trade-secret and buy the secret 626f73ff0001010425002302210288be11d147e1525f7f234f304b094d6627d2c70f3313d7ba3696887b261c4447 to gain access to the private Telegram group.

Or if you can't use bos yet you can ask about it on the public group

Example Commands

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

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

# Get the number of days the node cert remains valid
bos cert-validity-days

# Receive on-chain funds via a regular address
bos chain-deposit

# See the current fee estimates confirmation targets
bos chainfees

# Show chain fees paid
bos chart-chain-fees

# Show routing fees earned
bos chart-fees-earned

# Show routing fees paid
bos chart-fees-paid

# Show a chart of payments received
bos chart-payments-received

# Remove old failed payment data for probes and other failed payments
bos clean-failed-payments

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

# Export credentials
bos credentials

# View outbound fee rates and update outbound fee rates to peers
bos fees

# 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

# Create a signed raw transaction for an on-chain transfer
bos fund "address" "amount"

# See help about a command
bos help "command"

# Run gateway service for https://ln-operator.github.io/ UI
bos gateway

# Look up the channels and fee rates of a node by its public key
bos graph "pubkey"

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

# Enforce rules on inbound channels
bos inbound-channel-rules

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

# Increase the outbound liquidity of the node
bos increase-outbound-liquidity

# View and adjust list of saved nodes
bos nodes

# Open channels to public keys in a batch transaction
bos open "public_keys..."

# Open a balanced channel with a peer
bos open-balanced-channel

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

# Pay a payment request (invoice), 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

# Remove all channels with a peer
bos remove-peer

# Get a general report of the node activity
bos report

# Send funds using keysend and an optional message to a node
bos send

# Connect up to a Telegram bot
bos telegram

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

# Show unspent coin outputs
bos utxos

Community HowTos:

The accounting command howto
The open command howto
The rebalance command howto
Another rebalance command howto
Running rebalance video (In German)
Secrets of rebalance command revealed
Running telegram via nohup/tmux howto
Running telegram via systemd
Another rebalance + tags & telegram commands howto
Documentation for bos commands commands howto

Want to stack some sats? Write your own LN paywalled guide!

Nodes

By default bos expects tls.cert in the root of the default lnd directory and admin.macaroon in <default_lnd_dir>/data/chain/bitcoin/<network>.

Default LND directories:

macOS: ~/Library/Application Support/Lnd/
Linux: ~/.lnd/

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

The LND directory can be overriden with an environment variable:

BOS_DEFAULT_LND_PATH=/path/to/lnd/data/dir

Saved Nodes

If you have another node and it is already using balanceofsatoshis, you can add it as a "saved node" using bos nodes --add.

Otherwise you can copy the credentials into a saved nodes directory:

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

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

~/.bos/YOUR_NODE_NAME/credentials.json

Use any shorthand you'd like when choosing this profile node name

Each file should have the following format:

{
  "cert": "base64 tls.cert value",
  "macaroon": "base64 .macaroon value",
  "socket": "host:port"
}

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 -w0 ~/.lnd/tls.cert

# For `macaroon`
base64 -w0 ~/.lnd/data/chain/bitcoin/mainnet/admin.macaroon

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

You can also set cert_path and macaroon_path to the path of the relevant files instead.

The BOS directory path can be overriden with an environment variable:

BOS_DATA_PATH=/path/to/bos/data/dir

Umbrel Saved Node

Note: Umbrel is not FOSS software, use at your own risk.

If you are using Umbrel and you have already installed but you get an error like Name resolution failed for target dns:umbrel.local:10009 then try adding umbrel.local to your /etc/hosts file, like sudo nano /etc/hosts and add a line 127.0.0.1 umbrel.local

Identify your Umbrel home dir, like /home/umbrel/umbrel
Look in the .env file in that dir for the LND_IP to use as the socket to connect to

You can also use umbrel.local if that is in your Umbrel TLS cert but you will have to make sure the hostname is known to the client.

{
  "cert_path": "/home/umbrel/umbrel/app-data/lightning/data/lnd/tls.cert",
  "macaroon_path": "/home/umbrel/umbrel/app-data/lightning/data/lnd/data/chain/bitcoin/mainnet/admin.macaroon",
  "socket": "LND_IP:10009"
}

Now when you do a command, specify --node umbrel or whatever your dir is: bos --node umbrel balance

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

If a saved node is actually your default node, you can set an environment variable to avoid adding the --node prefix

export BOS_DEFAULT_SAVED_NODE=nodename

If that is set, it will use that node if no node is specified.

You can also add a JSON file to your .bos directory: config.json, add {"default_saved_node": "nodename"} to set the default via a file instead

Linux Fu

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

Open many channels

Make a textfile in the terminal with newline separated pubkeys and the capacity of the channels.

cat bos_channels.txt

       │ File: bos_channels.txt
───────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
   1   │ 0337...1986 --amount=3000000
   2   │ 02a4...20de --amount=3000000
   3   │ 023c...0dec --amount=1000000

bos open $(cat bos_channels.txt)

Summarize Numbers

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

Auto Adjust Fees

# Cron every 5 minutes adjust fees
*/5 * * * * /bin/timeout -s 2 30 /home/ubuntu/update-fees.sh

update-fees.sh:

#!/bin/bash
# Raise the outboun

Balanceofsatoshis

Install / Use

README