Boltz

Start with the direction. If you hold bitcoin on the mainchain and want to fund a Lightning wallet, you use a Submarine Swap: you pay on-chain, through a transaction recorded in the blockchain, and receive through Lightning. A Reverse Swap goes the other way. You pay a Lightning invoice, a payment request containing the relevant details, and gain the ability to collect funds on-chain. A Chain Swap connects two chains, such as Bitcoin and Liquid. For the latter two types, your app must broadcast a claim, the transaction that actually collects your funds. Paying does not therefore finish your part of the process. On Liquid, you receive L-BTC, an asset of that separate network, rather than an ordinary output on Bitcoin’s mainchain. Check the destination network before confirming. [1]

Imagine a server sends you an address and an amount to pay. Without further checks, you would simply be trusting that they match the agreed swap. The Boltz client, the app running on your device, should calculate the amount itself and check the payment hash in the Lightning invoice. A hash is a calculated fingerprint linking the payment to the right swap. The app also checks the address and script, the conditions determining who can spend the funds and when. With Taproot, a way of constructing a Bitcoin output, this includes the keys and script tree, which organizes the possible spending conditions. Ordinary users are not expected to calculate this by hand; the point is to use a client that actually performs the checks. The open boltz-web-app code allows scrutiny, but does not by itself prove that another integration or the app currently loaded in your browser is correct. [5] [9]

A swap address is not an account where you gradually collect the required amount. Boltz documentation requires a single lockup transaction, the initial transfer that locks funds under the swap’s rules. Later payments to the same address are not added to it; only the first is used for the swap. If you accidentally send too little, do not automatically send the difference. For a Chain Swap, the client may offer a new quote based on the amount received instead of refunding it. Enough time must remain, the amount must satisfy the limits and no refund signature may have been created. The service must also have sufficient funds available. This is a specific process for an incorrectly funded Chain Swap, not permission to top up any failed transfer. [2] [8]

To compare costs, follow the whole transfer rather than just the advertised percentage. Boltz charges a service fee, while transactions on the respective chains have their own costs. In a Reverse Swap, technical details include onchainAmount: the amount Boltz locks for you after accounting for its lockup fee. This is not yet the net amount reaching your wallet because you also pay for your claim, the transaction collecting those funds. In a Chain Swap, you pay for the transaction sending funds at the start as well. Compare what you spend in total with what you ultimately receive. Rates, minimums and limits apply to the particular direction and pair of networks, and can change with network conditions. An old promotional example is not a current quote. [6]

If a Submarine Swap or Chain Swap fails after you have sent funds, recovering them may require your own transaction. You need the refund key and saved swap information. With Taproot, a cooperating Boltz can enable a faster key path refund, a jointly signed return without waiting for the time condition. If cooperation is unavailable, the script path provides a return under the predetermined script once the timelock, a time restriction in the transaction rules, is satisfied. That option does not broadcast a transaction by itself; the client still has to do it. Cancelling an unsettled Lightning payment in a Reverse Swap is a different situation, releasing the pending funds back. It does not imply automatic recovery after every app failure or missed claim. [3]

For a Reverse Swap, settling the Lightning payment and collecting your on-chain funds are different events. The invoice.settled status can mean Boltz received the preimage, a secret value that allows the payment linked to its hash to complete. The server does not track whether your app then actually broadcasts the claim. The client must therefore verify its own output, the funds intended for you, and collect it before the timeout, the point after which the other side can recover it. A closed app, lost data or a transaction fee that is too low can complicate completion. A phone notification may help wake the app, but it does not replace a broadcast transaction. Judge the result by actual receipt, not just a green success message. [1] [2]

An ordinary wallet backup may not contain everything a pending swap needs. The Boltz Rescue Key is a set of backup words for a supported recovery process. Swap Restore uses it to reconstruct supported UTXO swaps, exchanges involving individual unspent transaction outputs. The client derives an xpub, an extended public key used to locate related swaps, and the corresponding private keys. A claim also requires the correct recovery of the preimage. An arbitrary seed, the starting secret of another app, is therefore not automatically usable: derivation methods and recovery formats must match. Private keys stay on your device. Sending the xpub cannot enable spending, but does reveal your swap history to Boltz’s server. Keep the particular client’s records and any older refund files alongside the ordinary wallet backup. [4] [2]

A transaction can appear on the network before it enters a block. Accepting it at that stage is called 0-conf, or zero-confirmation acceptance. Boltz documentation says it does not accept such user deposits on Bitcoin’s mainchain because of full-RBF adoption: rules that, under certain conditions, allow an unconfirmed transaction to be replaced by one paying a higher fee even without original opt-in signaling. In a Reverse Swap, the recipient instead bears the risk if they accept an unconfirmed transaction. Rules for one network pair cannot be assumed to apply to every other pair. Nor does accessible documentation prove the service currently has enough funds for your transfer. Before paying, check the current parameters, the time available to finish and the state of the particular swap. [7] [6]