Skip to main content
Submarine, reverse, and chain swaps follow the Boltz /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.

WebSocket

Atomic RGB swaps

Atomic swaps have no lockup and no refund: one transaction moves both legs. The client’s rgb-lib wallet signs; the maker signs last and broadcasts.