Skip to main content

​
Overview

Gateway is non-custodial. Swaps are atomic and secured by an on-chain Bitcoin Light Client, so a solver can never take a user’s funds without delivering the other side of the swap. If a swap can’t be completed, the user gets their funds back. This page explains when and how that happens.

​
When a refund happens

There are two situations where funds are returned instead of the expected output:
  • A DeFi action fails (BTC to X). When a swap includes a strategy or DeFi action — staking, lending, a multicall — and that on-chain action reverts, Gateway falls back to delivering wrapped BTC directly to the user’s EVM address rather than failing the whole swap. The user still receives value; they just receive wrapped BTC instead of the intended position.
  • An order gets stuck or can’t be filled. If no solver completes the order — for example a solver goes offline, or an X-to-BTC payout is never made — the locked funds can be reclaimed. The order status carries a refundTx you submit to unlock them.

​
BTC to X refunds

For BTC-to-X swaps, refunds take the form of the fallback described above: if the destination action fails, the user receives wrapped BTC on their EVM address instead. There’s no separate reclaim step — Gateway delivers the fallback asset automatically once the Bitcoin payment is verified.
Always test strategies thoroughly on testnet. A fallback means the user received wrapped BTC rather than the position they intended to open.

​
X to BTC refunds

For X-to-BTC swaps, the user first locks wrapped BTC in a Gateway contract while a solver fulfils the Bitcoin payout. If the payout doesn’t happen, the user has two options:
  1. Bump the fee. If Bitcoin network fees spiked after the order was created, the payout can be sped up. In V2 the gateway manages BTC fee bumps internally for the payout it broadcasts.
  2. Reclaim the locked funds. After a claim-delay period, the user can unlock their wrapped BTC and have it returned.
Reclaiming is irreversible. Once an order is refunded/unlocked, it cannot be resumed.
Because users cannot currently submit Bitcoin proofs themselves, an order may be temporarily “stuck” if the relayer is offline. Funds remain safe and become reclaimable — they cannot be taken by the relayer or a solver.

​
Refund status in the API

A completed refund shows up as the refunded order status, which lists the refundedTokens actually returned (each with chain, token, amount, and the settlement txHash). While an order is still in progress or has failed, a refundTx may be available to trigger the reclaim:
  • status.inProgress.refundTx — refund available on an in-progress order
  • status.failed.refundTx — refund available on a failed order
  • status.refunded.refundedTokens — the completed refund

​
Issuing a refund

When a refundTx is present, submit it as a normal EVM transaction to reclaim the locked assets. See the step-by-step code in the integration guide:

Refund stuck orders

Detect a refundable order and submit its refundTx

​
Next Steps

Fees

The full Gateway fee breakdown

Deep Dive

How verification and settlement work end to end