Swap Guides
This section helps you choose the guide for the exact swap your app is executing. Each page covers one swap family in detail, including the protocol behind it, the required wallets or signers, the manual execution path, and the recovery actions that matter when the automatic flow does not fully finish.
Use this section together with Executing Swaps. The quick-start page explains the shared high-level execute() flow, while the swap guides explain what changes from one swap family to another.
Usage
The simplest way to choose a guide is by the Bitcoin layer involved in the swap:
Bitcoin On-Chain (L1)
| Source | Destination | SwapType | Swap Class | Guide | Primitive |
|---|---|---|---|---|---|
| BTC L1 | Smart Chain | SPV_VAULT_FROM_BTC | SpvFromBTCSwap | Bitcoin → Smart Chain | UTXO-controlled vault |
| Smart Chain | BTC L1 | TO_BTC | ToBTCSwap | Smart Chain → BTC/Lightning | PrTLC |
Bitcoin Lightning (L2)
| Source | Destination | SwapType | Swap Class | Guide | Primitive |
|---|---|---|---|---|---|
| Lightning | Smart Chain | FROM_BTCLN_AUTO | FromBTCLNAutoSwap | Lightning → Smart Chain | LP-initiated HTLC |
| Smart Chain | Lightning | TO_BTCLN | ToBTCLNSwap | Smart Chain → BTC/Lightning | HTLC |
The Lightning guides also cover the LNURL-based variants of these swaps: Smart Chain → BTC/Lightning includes LNURL-pay, while Lightning → Smart Chain and Lightning → Solana include LNURL-withdraw flows.
Legacy Solana Swaps
The Solana guides are separate because the Bitcoin/Lightning → Solana direction still uses older protocol flows with different requirements and recovery behavior than the newer Starknet and EVM swaps. The reverse Smart Chain → Bitcoin/Lightning direction is the same across Solana, Starknet, and EVM.
| Source | Destination | SwapType | Swap Class | Guide | Primitive |
|---|---|---|---|---|---|
| BTC L1 | Solana | FROM_BTC | FromBTCSwap | Bitcoin → Solana | PrTLC |
| Lightning | Solana | FROM_BTCLN | FromBTCLNSwap | Lightning → Solana | User-initiated HTLC |
Topics
Standard Swaps
Use these guides for the standard swap flows used across Starknet and EVM, as well as for the common Smart Chain → Bitcoin/Lightning flow shared across Solana, Starknet, and EVM.
Smart Chain → BTC/Lightning | Bitcoin → Smart Chain | Lightning → Smart Chain
Legacy Swaps
Use these guides when the destination is Solana and the source is Bitcoin on-chain or Lightning, since those swaps still follow the legacy Solana-specific flows.
Bitcoin → Solana | Lightning → Solana