Before you integrate relay bridge, plan for a failed destination fill and a completed refund as separate outcomes: a confirmed origin deposit cannot be reversed. Record the request ID, deposit transaction, refund address and minimum output, then reconcile the request until you can verify a destination fill, an origin refund or a recovery path.
How relay bridge handles a failed fill
A failed fill can lead to an origin-chain refund, but failure alone does not prove that funds have returned. In a protocol-settled order, the user deposits into a Depository and a solver uses its own capital for the destination fill. If that fill cannot proceed, the solver may instead pay the user on the origin chain; an attestation then settles the refund against the deposit. Relay describes this as a fast refund.
If your integration needs to offer a replacement transfer after a refund, you can build another quote and execution flow, or send the user to relay bridge to move or swap assets across chains in one flow. For a relay bridge between chains, make that choice only after matching the refund to the original request. A second deposit while the first outcome is unresolved creates two live transfers.
Classify the failure by where it happened. These cases need different handling:
-
Before deposit: A quote error such as insufficient liquidity or an invalid input leaves no confirmed origin deposit to refund.
-
At deposit: Too little value, the wrong token or a mismatched chain can prevent the request from being filled.
-
At destination: Slippage, a reverted call or insufficient solver capacity can stop a fill after the origin deposit is confirmed.
-
During refund: A balance below the transfer threshold or insufficient value after gas can prevent an automatic return.
The refund amount and asset depend on the executed route
A refund is based on the funds that reached the deposit leg, less the cost of returning them; it is not necessarily the wallet’s original input amount. Set refundTo explicitly when quoting, and verify that the address can receive assets on the origin chain. Relay attempts to return the original currency, but an origin swap or route constraint can change what is available to return. Its refund rules also state that a refundable amount too small to cover gas may receive no automatic refund.
Say your user swaps a token into USDC on Arbitrum before a cross-chain fill. If the input leg produces 98 USDC from an illustrative 100 USDC worth of input, the refundable balance starts from the 98 USDC delivered to the Depository. Refund gas can reduce it further. Showing “100 USDC returned” because the first wallet transaction succeeded would overstate both the amount and possibly the asset.
The key pricing guard is the quoted minimumAmount, rather than the expected output. A quote may be regenerated when the deposit is processed; if its new minimum falls below the accepted minimum, Relay can refund instead of filling. For example, a 50 basis point slippage tolerance means 0.5%, but the right tolerance depends on pool depth, volatility and how long the deposit takes to confirm. Raising it reduces price-related refunds while allowing a worse fill.
Status and transaction evidence determine the outcome
Use the request ID to track execution, then use transaction hashes to establish what happened on each chain. GET /intents/status/v3 distinguishes waiting, pending, submitted, delayed, success, failure and refund. Treat success as a destination fill and refund as a completed return; investigate failure before telling the user their funds are back.
For diagnosis, read failReason and refundFailReason on the request. A SLIPPAGE fill failure suggests a new quote after recovery. AMOUNT_TOO_LOW_TO_REFUND points to a return that could not be sent. A TRANSACTION_NOT_INCLUDED fill has a recorded hash that might still confirm, so check it on-chain before treating another submission as safe.
There is one indexing trap when you bridge crypto with Relay through a deposit address. Relay can regenerate the quote and fill under a new request ID while the quote-time ID remains waiting. Query GET /requests/v3 by deposit address and inspect the replacement request before declaring the deposit missing.
A recovery workflow needs a separate decision for each state
Build recovery around evidence of the deposit, fill and refund, in that order. Persist the quote’s identifiers and limits before asking the wallet to sign; a browser session or callback is not a durable transaction record.
-
Save requestId, refundTo, input asset, amount, destination recipient and quoted minimumAmount with the user’s operation.
-
Record the origin transaction hash and confirm its receipt before marking the deposit as funded.
-
Poll GET /intents/status/v3 or consume status events, and reconcile each update against the stored request ID.
-
On failure, fetch the request’s failure fields and inspect any recorded destination hash before choosing a retry or recovery path.
-
On refund, verify the origin-chain return to refundTo, including the actual asset and amount, before enabling a replacement transfer.
For protocol-settled deposits that remain unfilled and unrefunded, check whether the credited balance is withdrawable through Relay’s recovery flow. Keep that case distinct from an automatic refund: it may require a user-triggered withdrawal and another origin-chain transaction. I would ship the integration with refund reconciliation and duplicate-deposit protection before offering a one-tap retry.