Swap lifecycle

A swap progresses through a fixed set of statuses.

​

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
• If the swap cannot be completed for any other reason (e.g. price moved beyond slippage tolerance) → Layerswap retries automatically.
  • With refund_address → if retries are exhausted, moves to pending_refund
  • Without refund_address → Layerswap keeps retrying. The swap remains in ls_transfer_pending until resolved.
• 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

​

Transaction-level detail

A swap can include multiple transactions, such as the deposit, payout, refuel, or refund. Each transaction has its own type 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 the GET /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 with GET /swaps/by_transaction_hash/{hash}.
• Webhooks: receive dashboard-configured status updates — Webhooks.
• Widget: use onSwapStatusChange to receive {type, swapId, path?}.

​

Next

Build your first API swap applies this lifecycle end to end. Refunds explains refund handling, addresses, fees, and transaction data. Track swaps covers polling, filters, and transaction-hash lookup.