Receiving Capacity

Your endpoints get paid over the Lightning Network. For a payment to reach your node, the node needs receiving capacity: room on the incoming side of a payment channel. This guide explains the capacity warnings bolthub can show you and walks through fixing each one.

Most of this is self-service from your node dashboard at bolthub.ai/nodes/{your-node}. Open it in another tab and follow along.

What is receiving capacity?

Think of a channel as a two-way pipe for payments. When API consumers pay you, sats flow into your side of the pipe (your receiving capacity drops and your spending balance rises). When the pipe fills up, your node can Loop Out: sweep the received sats to your on-chain wallet, which frees the pipe to receive again.

So capacity is not a hard cap. For typical bolthub calls (10–100 sats each), 100k sats of capacity handles roughly 1,000–10,000 payments before it needs to refill, and refilling happens automatically once Loop Out is enabled.

Set up your first channel

You will see "Your node has no payment channels" (in the dashboard and by email) when your node has no channels yet. Until you add one, API consumers get an error when they try to pay, so no payments come through. Nothing is lost; they simply do not go through.

The fastest fix is to order receiving capacity from your dashboard:

1. Open your node at bolthub.ai/nodes/{your-node}.
2. In the Receiving capacity section, pick a size. Start with 100k sats, which is plenty for most APIs and refills automatically.
3. Click Set Up Capacity (or 1-click 100k channel to skip the picker).
4. You will get a Lightning invoice for a one-time setup fee. Pay it from any Lightning wallet (Phoenix, Wallet of Satoshi, Muun, Strike, or similar) by copying the invoice or scanning the QR code.
5. As soon as the invoice is paid, the liquidity provider opens the channel to your node. The dashboard updates to "All channels online" within a few minutes.

What the setup fee covers

The fee (typically 1–2% of the capacity) is a one-time service fee paid to the liquidity provider that opens your pipe. It is not deposited into your wallet, and it is separate from your API earnings, which go directly to your node. The provider guarantees the channel stays open for at least 12 weeks; if it ever closes, any remaining balance settles to your on-chain wallet automatically.

Prefer to run your own channels?

If you would rather open channels yourself, fund your node's on-chain wallet and open a channel from Lightning Terminal (the admin UI on your server, at https://{'{your-node-ip}'}:8443). Then click Skip for now on the capacity prompt. bolthub will detect the channel on its next health check.

Free up full capacity

You will see "Your receiving capacity is full" or "Your receiving capacity is running low" when your channels are healthy but most of the inbound room has been used by payments you already received. New payments fail until you free up space.

The fix is Loop Out, which moves received sats to your on-chain wallet and reopens the pipe:

1. Open Lightning Terminal on your node (https://{'{your-node-ip}'}:8443).
2. Go to the Loop tab and open Autoloop Settings.
3. Enable Autoloop so the node rebalances on its own in the background (a small fee, around 0.5%, applies to each loop).

Once Autoloop is on, capacity refills automatically and you should not see this warning again. You can also add a second channel from the dashboard for more headroom.

Node temporarily disconnected

You may get an email saying your node is temporarily disconnected from its channel peers. This is different from having no channels: your channels and balances are fully intact, but your node briefly lost its live connection to the peer, so it cannot route payments for that moment.

This almost always clears on its own once the peer reconnects, and bolthub only emails after the disconnect has lasted several minutes. If it persists:

• Check that your node is online and reachable on port 9735.
• Confirm your node is advertising a public address (open Lightning Terminal and check your node's URIs).
• If you run a firewall, make sure inbound connections on port 9735 are allowed.

How bolthub checks your node

bolthub reads your node's live state every 5 minutes using a read-only monitoring key. It can see balances, channels, and peers, but it cannot move your funds. Capacity warnings only fire after a problem has persisted across several checks, and you will get at most one email per day per node.

Need more help? Reach out from your dashboard and include your node ID.