/v2 protocol. Both legs of a swap are locked to the hash of one secret, the preimage: the Lightning payment as a hold invoice, and the on-chain funds in a Taproot output that can be claimed with the preimage or refunded after a timeout. Claiming reveals the preimage, which settles the other leg.
Every swap
1
Pick a pair
GET /v2/swap/{type}/pairs returns from → to → card. Check the amount against the card’s limits and keep its hash.2
Create
POST /v2/swap/{submarine,reverse,chain} with your public key(s) and pairHash. Send your organization key or API key here if you have one. Store the full response, including swapAuth.3
Verify before funding
Rebuild the swap tree from your own key, the maker’s
refundPublicKey or claimPublicKey, the preimage hash, and timeoutBlockHeight. Derive the Taproot address and compare it with the response. For reverse swaps, decode the invoice and check that its payment hash is your preimage hash. Do not fund a swap that fails any check.4
Fund or pay
Fund the lockup with exactly the expected amount in one transaction, or pay the invoice.
5
Follow status
GET /v2/swap/{id}, or subscribe on GET /v2/ws.6
Claim or refund
Claim cooperatively through the claim endpoint, or alone through the script path. Refund cooperatively before the timeout, or alone after it.
Submarine: on-chain → Lightning
Reverse: Lightning → on-chain
The claim must confirm before
timeoutBlockHeight. If the maker does not cooperate, spend the claim leaf with the preimage and your signature.
Chain: on-chain → on-chain
Two ways to answer a re-quote. When you lock a different amount than quoted, the maker proposes a new destination amount and the swap waits for a decision.
POST /v2/swap/chain/{id}/quote is the Boltz-compatible route: it accepts the exact proposed amount, and it is what the Swap SDK’s acceptQuote calls. POST /v2/swap/{id}/rate-decision answers the same proposal with accept: true or accept: false; rejecting moves the swap to its refund. Both need X-Swap-Auth.
Status values
A status is the maker’s report. Check lockups and the chain tip on your own chain backend before claiming or refunding.