Balance of Satoshis (BOS)

What Is Balance of Satoshis?

Balance of Satoshis (commonly called "bos") is a free, open-source command-line toolkit for operating Lightning Network nodes running LND. Created and maintained by Alex Bosworth, a developer at Lightning Labs, BOS provides a suite of commands that simplify the day-to-day operations of running a routing node: rebalancing channels, analyzing forwarding revenue, adjusting fee policies, and generating accounting reports.

Running a Lightning routing node involves constant operational work. Channels drift out of balance as payments flow through them, fee policies need adjustment to stay competitive, and operators need visibility into which channels are profitable. BOS addresses these challenges through scriptable, composable CLI commands that can be run manually or automated via cron jobs and Telegram bot integrations.

BOS is distributed as an npm package and exclusively supports LND. It does not work with Core Lightning or Eclair implementations.

How It Works

BOS connects to an LND node through its gRPC API using macaroon-based authentication. Once connected, it exposes dozens of commands that interact with the node's channels, payments, invoices, and on-chain wallet. Every command runs in the terminal and outputs structured text that can be piped to other tools or parsed by scripts.

Installation

BOS requires Node.js and npm. Installation is a single command, or operators can use npx to try commands without a permanent install:

# Install globally
npm install -g balanceofsatoshis

# Or run a one-off command without installing
npx balanceofsatoshis help

After installation, the bos command becomes available. Running bos help lists all available commands, and bos help <command> shows usage details for any specific command.

Core Command Categories

BOS commands fall into several operational categories:

• Liquidity management: rebalancing channels, opening balanced channels, and managing inbound and outbound liquidity
• Fee management: viewing and adjusting routing fees per channel, setting forwarding policies, and analyzing fee revenue
• Accounting: generating transaction ledgers with fiat conversion, exporting to CSV for tax reporting, and tracking routing income over time
• Network analysis: probing routes, inspecting peer nodes, viewing channel graphs, and summarizing forwarding history
• Channel operations: opening channels (including batched opens), closing channels, and enforcing inbound channel rules

Channel Rebalancing

The most widely used BOS feature is bos rebalance, which performs circular rebalancing. This routes a payment from one of your own channels back to another of your own channels, shifting liquidity without involving a counterparty. The goal is to keep channels balanced so the node can route payments in both directions.

# Rebalance from an outbound-heavy channel to an inbound-heavy one
bos rebalance --out OUTBOUND_CHANNEL_ID --in INBOUND_CHANNEL_ID --max-fee-rate 250

# Auto-target 50% inbound on a channel
bos rebalance --out-target-inbound capacity/2 --in CHANNEL_ID

The --max-fee-rate flag caps the cost of rebalancing in parts per million (PPM), preventing operators from overpaying for liquidity shifts. BOS also supports formula-based parameter expressions that can reference channel capacity and fee rates, along with an --avoid flag to exclude specific nodes or channels from the route.

Key Commands

Accounting and Reporting

The bos accounting command generates a formatted transaction ledger that categorizes on-chain and off-chain activity. It supports fiat conversion using exchange rate data from CoinDesk or CoinGecko, making it useful for tax preparation:

# View chain transaction accounting
bos accounting "chain-fees"

# View routing fee income
bos accounting "forwarding"

The output can be exported to CSV for import into accounting software, providing routing node operators with structured records of their forwarding income and on-chain costs.

Forwarding Analysis

The bos forwards command provides a summarized view of which peers are generating the most forwarding revenue. This helps operators identify their most valuable channel partners and decide where to allocate additional liquidity. Combined with bos graph (which looks up a node's channels and fee rates by public key), operators can evaluate potential peers before opening channels.

Channel Opens and Rules

BOS supports batched channel opens, combining multiple channel openings into a single on-chain transaction to reduce fees. The bos open-balanced-channel command coordinates with a peer to open a channel where both sides contribute funds, resulting in immediate bidirectional capacity. The bos inbound-channel-rules command lets operators set automatic policies for accepting or rejecting incoming channel requests.

Telegram Integration

BOS includes a Telegram bot integration that allows operators to monitor their node remotely. The bot can send notifications about channel events, forward summaries, and balance changes, and operators can execute certain commands directly through Telegram messages.

Why It Matters

Running a profitable routing node is operationally demanding. Channels constantly shift out of balance as payments flow through them in one direction. Without rebalancing, a node quickly becomes unable to route payments and stops earning routing fees. BOS gives operators the tools to maintain healthy channel balances and optimize their fee structures.

The tool's CLI-first design makes it particularly valuable for automation. Operators can script rebalancing routines, schedule accounting exports, and build custom monitoring pipelines. This programmability is difficult to achieve with GUI-based alternatives. For node operators who manage channels across the Lightning Network and need precise control, BOS remains a core part of the operational toolkit.

For a deeper look at channel management strategies and routing economics, see Lightning Channel Management Guide and Lightning Node Profitability and Routing Analysis.

Comparison With Alternatives

BOS is one of several tools available to Lightning node operators. The right choice depends on whether an operator prefers a CLI workflow or a graphical interface, and which Lightning implementation they run.

ThunderHub provides a polished web interface with visual channel management, fee dashboards, and two-factor authentication. It supports newer LND features like Taproot Assets. RTL is the most implementation-agnostic option, supporting LND, Core Lightning, and Eclair, making it the default choice for operators running non-LND nodes.

Many experienced operators use BOS alongside a GUI tool: BOS for scripted automation and rebalancing, and ThunderHub or RTL for visual monitoring and ad-hoc management. The tools are complementary rather than mutually exclusive.

Other specialized tools in the same ecosystem include Autoloop for automated Loop operations and charge-lnd for automated fee policy management.

Risks and Considerations

LND Lock-In

BOS only works with LND. Operators running Core Lightning or Eclair cannot use it. This makes BOS a factor in implementation choice: operators who rely heavily on BOS workflows are effectively tied to LND.

Rebalancing Costs

Circular rebalancing is not free. Each rebalance pays routing fees to the intermediate nodes along the path. Poorly configured rebalancing (high max fee rates, unnecessary frequency, or rebalancing unprofitable channels) can cost more in fees than the routing revenue those channels generate. Operators should track their rebalancing costs against forwarding income to ensure net profitability.

CLI Complexity

BOS is a power-user tool with a learning curve. Commands have many flags and options, and formula-based parameter expressions add flexibility at the cost of simplicity. New node operators may find GUI alternatives more approachable for initial node management before graduating to BOS for advanced automation.

Single Maintainer Risk

While BOS is open source, it is primarily maintained by a single developer. The project depends on continued maintenance to stay compatible with new LND releases. Operators should be aware of this dependency and monitor the GitHub repository for activity and compatibility updates.

This glossary entry is for informational purposes only and does not constitute financial or investment advice. Always do your own research before using any protocol or technology.