Skip to main content
When a swap cannot be completed after the user has sent funds, Layerswap may initiate a refund to refund_address. The refund is always processed on the source chain in the source token. Gas fees for processing the refund transaction are deducted from the refund amount.

When does a refund happen?

  • Price changes: Layerswap cannot obtain an executable quote that meets the swap’s minimum receive amount.
  • Insufficient liquidity: The solver does not have enough liquidity to complete the transaction.
  • Provider execution failure: A swap provider (e.g. a DEX) encountered an error during execution.
  • Destination chain unavailability: The destination chain is unavailable due to an RPC outage or chain reorganization.
Layerswap may retry failed operations before initiating a refund. Retry behavior and timing depend on the failure. An automatic refund requires a refund_address. Without a refund address, recovery depends on the failure. The swap may remain ls_transfer_pending during retries or investigation, or move to failed. Check fail_reason when a swap fails.

Refund statuses

When a refund is initiated, the swap transitions to pending_refund. Once the refund transaction is confirmed on-chain, the status changes to refunded. See the Swap lifecycle for the full status flow and the what can go wrong matrix.

Refund address

You can provide a refund_address when creating a swap. This must be a valid address on the source network. If the swap route involves a swap provider, the refund address is required unless use_deposit_address is enabled. A missing required address returns REFUND_ADDRESS_MISSING. Supplied refund addresses are validated against the source network even when optional.

Refund amount

The refund is sent in the source token, minus the source-network gas fee for the refund transaction. If the refund amount is less than the gas fee, no refund is issued.

Identifying a refund transaction

A refunded swap will have a transaction with type: "refund" in its transactions array. Read the swap with GET /swaps/{id}:
The response contains the swap with status: "refunded" and a refund transaction in the transactions array:
The refund transaction shows the on-chain transfer back to the user in the original source token. Each transaction has its own status; the swap-level status describes the overall lifecycle.

Next

Track swaps covers polling, webhooks, transaction-hash lookup, and status filters.