Getting Started Guide

1. What Is Boltz?

Boltz is a non‑custodial, trust‑minimized swap service built around atomic swap / submarine swap smart contracts. It lets you move sats between:

  • On‑chain Bitcoin (L1) ↔ Lightning Network (L2)
  • On‑chain Bitcoin (L1) ↔ Liquid Bitcoin (L‑BTC)
  • Lightning ↔ Liquid
  • Select side‑chains & alt UTXO assets (e.g. Litecoin, Testnet coins)

Unlike centralized bridges, Boltz holds no private keys. Funds are either in your wallet or in a hash‑time‑locked contract where you are one of the keys.

2. Core Concepts

2.1 Submarine Swaps & Atomicity

A submarine swap is an atomic swap between a layer‑2 (Lightning) and layer‑1 (on‑chain) asset using a shared pre‑image (secret) and time‑locks. Either both legs settle, or both refund.

2.2 Swap Directions

  • Normal swap: You start on‑chain and receive Lightning.
  • Reverse swap: You start Lightning and receive on‑chain.
    Each direction reverses who generates the secret and which side pays first.

2.3 Swap Life‑Cycle (High‑Level)

  1. Quote — Client fetches terms (rate, limits, fees).
  2. Lock TX / Invoice — On‑chain side locks funds; Lightning side creates invoice.
  3. Claim / Pre‑image — Receiver claims funds revealing secret.
  4. Payout — Other side uses secret to sweep.
  5. Refund path — If steps stall, contract refunds after timelock.

3. Supported Assets & Limits (July 2025)

Pair Min Max Platform Fee
BTC → LN 25 000 sats 0.1 BTC 0.1 %
LN → BTC 100 000 sats 0.25 BTC 0.5 %
BTC ↔ L‑BTC 10 000 sats 0.5 BTC 0.1 %
LN ↔ L‑BTC 10 000 sats 1 BTC 0.1 – 0.25 %

Limits & fees fluctuate with liquidity; always check the live quote screen.

Boltz sometimes offers negative fees (you get a rebate) to rebalance its inventory.

4. Getting Started

4.1 Choose Your Front‑End

4.2 Basic Web Swap Flow

  1. Open the site via Tor or clearnet.
  2. Select Send Asset / Receive Asset.
  3. Enter amount or click Max.
  4. Click Get Quote → review fees, expected on‑chain miner fee, expiry.
  5. Provide destination address / Lightning invoice.
  6. Confirm; follow step‑by‑step instructions (e.g., pay invoice or broadcast TX).
  7. Wait for Claimed status & (optionally) one block confirmation.

4.3 Wallet Embedded Flow (e.g., Phoenix)

  1. In wallet select Receive on‑chain (reverse swap) or Top‑up LN (normal swap).
  2. Wallet queries Boltz API behind the scenes and guides you through paying invoice or sending TX.
  3. Funds arrive seamlessly in other layer.

5. Fees & Quotes

Boltz splits cost into:

  • Boltz Fee — Percentage of swap amount (0.1–0.5 %).
  • Miner Fee — Estimate for on‑chain claim/refund TX; varies by mempool congestion.
  • Liquidity Incentive — Negative or additional fee if direction needs rebalancing.

All numbers are displayed before you commit. No hidden spreads.

6. No‑KYC, Privacy & Trust Model

  • No account / email — Just paste addresses/invoices.
  • Tor‑accessible — .onion mirror available (see footer links).
  • Script audit — Swap contracts & builder scripts are open‑source on GitHub.
  • Self‑custody — Refund path returns funds if Boltz disappears.
  • UTXO hygiene — Receiving new addresses avoids linkage; Lightning side has inherent privacy benefits.

Remember: Boltz sees your on‑chain address & Lightning invoice—and your IP if not on Tor. Use VPN/Tor for best privacy.

7. Troubleshooting

Symptom Likely Cause Fix
Swap stuck at "LOCKED" Mempool backlog; TX unconfirmed Wait or bump fee (RBF) if you control input.
"Route not found" error No LN path between your node and Boltz Use wallet with trampoline/probing; lower amount; try another LN wallet.
Timeout refund triggered Paid invoice late or node offline Funds auto‑return to refund address after locktime.
Fee seems high High miner fee estimate or reverse direction premium Try smaller size or swap when mempool low.

8. Advanced – Boltz API & CLI

Install CLI:

git clone https://github.com/BoltzExchange/boltz-cli
cd boltz-cli && npm install -g .
boltz-cli swap --pair btc/ln --amount 500000 --destination INVOICE

API Endpoints:

  • GET /api/v2/swapstatus/:id — Poll swap progress.
  • POST /api/v2/createswap — Initiate with JSON body.
  • GET /api/v2/listswaps — History for your pubkey.

Automated traders can watch Boltz Fee rails and arbitrage when rebates exist.

9. Glossary

Term Meaning
Submarine Swap Atomic swap between L1 and L2 using shared hash.
Reverse Swap Starts on Lightning, ends on‑chain.
HTLC Hash‑time‑locked contract safeguarding both legs.
Boltz Fee Platform service fee (0.1–0.5 %).
Negative Fee Liquidity rebate Boltz pays you.

10. Next Steps

  1. Test a small Lightning → On‑chain reverse swap (e.g., 200 000 sats).
  2. Integrate Boltz with your preferred wallet (Phoenix or Zeus).
  3. Explore Liquid swaps for cheaper fees during mempool spikes.
  4. Consider running your own Boltz watchtower script for auto‑refund monitoring.

Happy swappin, may your channels stay balanced and your coins stay yours! 🚀