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.
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 topending_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 arefund_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 withtype: "refund" in its transactions array. Read the swap with GET /swaps/{id}:
status: "refunded" and a refund transaction in the transactions array:
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.