Lightning Loop Tutorial: Submarine Swaps

What Is Lightning Loop?

Lightning Loop is a service by Lightning Labs that enables submarine swaps between the Lightning Network and on-chain Bitcoin. In practical terms, Loop lets you move bitcoin between your Lightning channels and the blockchain without closing channels — solving one of the most common operational challenges for node operators.

Two operations form the core of Loop:

• Loop Out: Sends sats from a Lightning channel to an on-chain address. This creates inbound liquidity in your channels while receiving bitcoin on-chain.
• Loop In: Sends on-chain bitcoin into your Lightning channels. This creates outbound liquidity, replenishing depleted channel capacity.

Both operations use submarine swaps — a trustless, atomic exchange mechanism that ensures either both sides of the swap complete or neither does. No trust in Lightning Labs is required for the swap itself; the cryptographic protocol guarantees the exchange.

Why Submarine Swaps Matter

Without submarine swaps, the only way to rebalance your Lightning liquidity is:

1. Close and reopen channels — expensive (two on-chain transactions), disruptive (loses routing capability during downtime), and slow (requires multiple confirmations).
2. Circular rebalancing — sends a payment from your node back to yourself through other nodes. This works but has limitations: it requires sufficient routing paths, costs routing fees, and does not add new liquidity to the network.

Submarine swaps add a third option that is non-disruptive, adds real liquidity, and can be automated. For a thorough understanding of why liquidity management matters, see our guide on Lightning channel management.

Prerequisites

• A running LND node (version 0.17.0 or later recommended)
• Basic familiarity with the command line
• At least one open Lightning channel with balance to swap
• An on-chain Bitcoin address for receiving Loop Out funds (or on-chain funds for Loop In)

If you run Umbrel or Start9, you can install Loop directly from the app store or run it via the command line. ThunderHub also includes Loop integration in its interface.

Installing Loop

Method 1: Umbrel App Store

1. Open your Umbrel dashboard.
2. Navigate to the App Store.
3. Search for “Lightning Loop” or “Loop.”
4. Click Install. The app automatically connects to your LND instance.
5. Access Loop through the Umbrel dashboard or via ThunderHub’s Loop integration.

Method 2: Command Line Installation

1. Download the Loop binary from the official Lightning Labs releases:

wget https://github.com/lightninglabs/loop/releases/download/v0.28.0-beta/loop-linux-amd64-v0.28.0-beta.tar.gz
tar -xzf loop-linux-amd64-v0.28.0-beta.tar.gz
sudo cp loop-linux-amd64-v0.28.0-beta/loop /usr/local/bin/
sudo cp loop-linux-amd64-v0.28.0-beta/loopd /usr/local/bin/

2. Start the Loop daemon (it connects to your running LND instance):

loopd --network=mainnet

3. Verify the connection:

loop terms

This command displays the current swap terms, including minimum and maximum amounts, fees, and timelock parameters.

Performing a Loop Out (Lightning → On-Chain)

Loop Out is the most common operation. It moves sats from your Lightning channels to an on-chain address, creating valuable inbound liquidity in the process.

Step 1: Check Current Terms

loop quote out 500000

This returns the estimated cost for looping out 500,000 sats. The output includes:

• Swap fee: The fee charged by Lightning Labs’ swap server.
• On-chain fee (est): The estimated miner fee for the on-chain transaction.
• Total cost: The sum of all fees. Typically ranges from 0.1% to 0.5% of the swap amount plus the on-chain fee.

Step 2: Execute the Loop Out

loop out --amt 500000 --conf_target 6

Parameters:

• --amt: Amount in satoshis to loop out.
• --conf_target: Target number of blocks for on-chain confirmation. Higher targets mean lower on-chain fees. Use 6 for normal speed, 144 for next-day (lowest fees).
• --dest (optional): Specific on-chain address to receive the funds. If omitted, Loop sends to your LND wallet’s internal address.

Step 3: Monitor the Swap

loop monitor

This streams real-time updates on your active swap. A Loop Out follows this timeline:

1. Initiated: Swap request sent to the Loop server.
2. HTLC published: The on-chain HTLC (hash time-locked contract) is broadcast by the Loop server.
3. Off-chain payment: Your node routes the Lightning payment to the Loop server.
4. Sweep: Once confirmed, the on-chain funds are swept to your destination address.
5. Completed: Swap finalized. Your channel now has increased inbound liquidity.

Total completion time depends on on-chain confirmation speed — typically 30-90 minutes.

Step 4: Verify Results

After the swap completes, check your channel balances:

lncli listchannels | jq '.channels[] | {chan_id: .chan_id, local: .local_balance, remote: .remote_balance}'

You should see reduced local balance (outbound liquidity) and increased remote balance (inbound liquidity) in the channel used for the swap.

Performing a Loop In (On-Chain → Lightning)

Loop In moves on-chain bitcoin into your Lightning channels, restoring outbound liquidity that has been depleted by spending.

Step 1: Get a Quote

loop quote in 500000

Step 2: Execute Loop In

loop in --amt 500000 --conf_target 6

Step 3: Fund the On-Chain Address

Loop In generates an on-chain address where you send the specified amount of bitcoin. Once the on-chain transaction confirms, the submarine swap executes and your Lightning channel balance increases.

loop monitor

The Loop In process typically takes longer than Loop Out because your on-chain transaction must confirm before the swap proceeds.

Advanced Loop Features

Autoloop: Automated Liquidity Management

Autoloop is Loop’s automated mode that maintains your channel liquidity within specified thresholds. Instead of manually executing swaps, you define rules and Autoloop handles execution.

1. Set liquidity rules for a specific channel:

loop setrule [channel_id] --incoming_threshold=25 --outgoing_threshold=25

This tells Autoloop to initiate a swap whenever a channel’s inbound or outbound capacity drops below 25% of the total channel capacity.

2. Configure Autoloop parameters:

loop setparams --autobudget=50000 --autobudgetrefreshperiod=168h --automaxfee=5000

Parameters:

• --autobudget: Maximum sats to spend on swap fees per budget period.
• --autobudgetrefreshperiod: How often the budget resets (168h = weekly).
• --automaxfee: Maximum fee per individual swap.

3. Enable Autoloop:

loop setparams --autoloop=true

4. Check Autoloop status:

loop suggestswaps

This shows which channels would trigger swaps under your current rules.

Loop with ThunderHub

If you use ThunderHub for node management, Loop operations are available through the graphical interface:

1. Navigate to the Tools section in ThunderHub.
2. Select “Loop” from the available tools.
3. Choose Loop Out or Loop In.
4. Set the amount, target channel, and fee preferences.
5. Execute and monitor through the ThunderHub interface.

ThunderHub’s integration makes Loop accessible to operators who prefer graphical interfaces over the command line.

Fee Optimization Strategies

Loop fees consist of two components: the swap server fee (paid to Lightning Labs) and the on-chain miner fee. For a broader understanding of how fees work across the network, see our Lightning Network fees complete guide. You can control the second component significantly:

• Use high conf_target values: Setting --conf_target 144 targets next-day confirmation, substantially reducing the on-chain fee. For non-urgent liquidity management, this saves significant sats.
• Batch multiple loops: If you need to rebalance multiple channels, execute all Loop Outs in quick succession. The swap server may batch on-chain transactions, reducing per-swap costs.
• Monitor on-chain fees: Execute loops during weekend or early-morning low-fee periods. Check mempool conditions before initiating swaps.
• Right-size your swaps: The swap server fee has a minimum, so very small swaps are proportionally expensive. Swapping 500,000+ sats per operation is more cost-effective than frequent small swaps.

Loop Alternatives

Loop is not the only submarine swap provider. Understanding alternatives helps you choose the best tool for your situation:

Boltz is a non-custodial exchange that supports submarine swaps between Lightning and on-chain Bitcoin (and also Liquid). Its lower minimums make it attractive for smaller swaps, and it does not require an account.

PeerSwap enables direct atomic swaps between channel peers without a third-party server. It is the most trustless option but requires your channel counterparty to also run PeerSwap. Available as a plugin for both CLN and LND.

Troubleshooting Common Issues

Swap Stuck in “Initiated” State

The on-chain HTLC has not been published. This can happen if the Loop server is under heavy load. Wait 10-15 minutes. If the swap does not progress, it will time out and cancel automatically. Your funds are safe — the atomic swap protocol ensures you cannot lose funds from a stalled swap.

High Quoted Fees

Loop fees increase during periods of high demand and high on-chain fees. If the quote seems expensive, wait for lower on-chain fee conditions or use a higher conf_target. You can also check Boltz for potentially lower rates.

“No Suitable Channels” Error

Loop Out requires a channel with sufficient outbound balance to fund the swap. If no single channel has enough capacity, reduce the swap amount or rebalance your channels first using circular rebalancing before looping.

FAQ

Can I lose funds during a Loop swap?

No. Submarine swaps use hash time-locked contracts that guarantee atomicity. Either both the Lightning payment and the on-chain transaction complete, or both are reversed. If the swap fails at any stage, your funds return to their original location. The worst outcome is paying on-chain fees for a transaction that gets refunded.

How much does a typical Loop Out cost?

A 500,000 sat Loop Out typically costs 1,000-3,000 sats in swap server fees plus the on-chain miner fee (variable based on confirmation target and current mempool conditions). During low-fee periods, total cost for this swap might be 2,000-4,000 sats. During high-fee periods, the on-chain component can increase substantially.

Is Loop available for Core Lightning nodes?

Lightning Loop is designed for LND and does not natively support CLN. For CLN-based submarine swaps, use Boltz (which offers a web interface and API compatible with any Lightning implementation) or PeerSwap (available as a CLN plugin). These alternatives provide similar liquidity management capabilities for CLN operators.

How often should I run Loop operations?

Frequency depends on your payment volume and channel usage patterns. High-volume routing nodes might loop weekly. Personal spending nodes might loop monthly or less. If you use Autoloop, the system handles timing automatically based on your configured thresholds. Monitor your channel balances and swap when channels become unbalanced enough to affect your routing or spending capability.

For a broader perspective, explore our running your own Bitcoin node guide.

{“@context”: “https://schema.org”, “@type”: “FAQPage”, “mainEntity”: [{“@type”: “Question”, “name”: “Can I lose funds during a Loop swap?”, “acceptedAnswer”: {“@type”: “Answer”, “text”: “No. Submarine swaps use hash time-locked contracts that guarantee atomicity. Either both the Lightning payment and the on-chain transaction complete, or both are reversed. If the swap fails at any stage, your funds return to their original location. The worst outcome is paying on-chain fees for a transaction that gets refunded.”}}, {“@type”: “Question”, “name”: “How much does a typical Loop Out cost?”, “acceptedAnswer”: {“@type”: “Answer”, “text”: “A 500,000 sat Loop Out typically costs 1,000-3,000 sats in swap server fees plus the on-chain miner fee (variable based on confirmation target and current mempool conditions). During low-fee periods, total cost for this swap might be 2,000-4,000 sats. During high-fee periods, the on-chain component can increase substantially.”}}, {“@type”: “Question”, “name”: “Is Loop available for Core Lightning nodes?”, “acceptedAnswer”: {“@type”: “Answer”, “text”: “Lightning Loop is designed for LND and does not natively support CLN. For CLN-based submarine swaps, use Boltz (which offers a web interface and API compatible with any Lightning implementation) or PeerSwap (available as a CLN plugin). These alternatives provide similar liquidity management capabilities for CLN operators.”}}, {“@type”: “Question”, “name”: “How often should I run Loop operations?”, “acceptedAnswer”: {“@type”: “Answer”, “text”: “Frequency depends on your payment volume and channel usage patterns. High-volume routing nodes might loop weekly. Personal spending nodes might loop monthly or less. If you use Autoloop, the system handles timing automatically based on your configured thresholds. Monitor your channel balances and swap when channels become unbalanced enough to affect your routing or spending capability. For a broader perspective, explore our running your own Bitcoin node guide.”}}]}