Flow
1. user_transfer_pending
Swap is created. Layerswap is waiting for the user to complete the transaction in the source network.
- If no deposit arrives within 6 hours →
expired - Once the deposit is confirmed with enough confirmations →
ls_transfer_pending
2. ls_transfer_pending
Layerswap is processing the swap. If something goes wrong during execution:
- If deposited amount is below the minimum →
failed - Layerswap may retry failed operations. Retry behavior and timing depend on the failure.
- With
refund_address→ a failure eligible for an automatic refund moves topending_refund. - Without
refund_address→ the swap may remainls_transfer_pendingduring retries or investigation, or move tofailed. - If execution succeeds →
completed
3. completed
Funds are delivered to the destination address.
4. pending_refund → refunded
Refund is sent to refund_address on the source chain in the source token, minus gas fees. If the refund amount is less than the gas fee, no refund is issued. See Refunds for details.
What can go wrong
See Refunds for refund handling and address requirements.
Transaction-level detail
A swap can include multiple transactions, such as the deposit, payout, refuel, or refund. Each transaction has its owntype and status. Use the transaction status to track that specific on-chain operation, use the swap-level status to track the overall swap lifecycle.
Filtering swaps by status
Status names used in API responses are different from those accepted by theGET /swaps filter. For example, a swap response uses pending_refund, while the corresponding filter value is PendingRefund.
See Track swaps for the complete list of filter values.
Observing status changes
- API: poll
GET /swaps/{id}, or look up by funding transaction withGET /swaps/by_transaction_hash/{hash}. - Webhooks: receive dashboard-configured status updates — Webhooks.
- Widget: use
onSwapStatusChangeto receive{type, swapId, path?}.