Handling Failures and Recovery

Cross-chain swaps are non-atomic as they span two chains and a bridge provider in between. If the origin transaction succeeds but the bridge cannot complete, the user’s funds have left their wallet and need to be recovered.

This page explains what happens when a bridge fails, how recovery works, and what your integration should do for each scenario. For the happy-path status lifecycle, see Tracking Transaction Status.

Origin refund vs dest retry

The recovery path depends on where the transfer fails.

Origin refund. If the bridge fails, the bridge provider automatically returns the tokens on the origin chain. The status changes from refund_pending to refund_succeeded when the refund is complete.

Dest retry. If the bridge provider’s call on the destination chain fails, /status returns manualTransaction: null and 0x retries that call. A successful retry changes the status to bridge_filled.

How Failures Surface

When you poll GET /cross-chain/status and the response has status: "bridge_failed", it includes a failure object with everything needed to understand what went wrong and what to do next.

Do not stop polling on bridge_failed while failure.status is refund_pending or manual_action_required. When a destination retry succeeds, the top-level status changes to bridge_filled and the failure object is removed.

Failure Object Structure

{
  "status": "bridge_failed",
  "bridge": "across_v4",
  "failure": {
    "reason": "expired",
    "status": "refund_pending",
    "transactions": [
      { "chainId": 8453, "txHash": "0xabc...", "timestamp": 1712345678 }
    ],
    "recovery": {
      "chainId": 8453,
      "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "amount": "2500000000",
      "estimatedTimeSeconds": 1200,
      "deadline": null,
      "manualTransaction": null,
      "settledAmount": null
    }
  }
}

Failure Reasons

Failure Statuses

Recovery Step Fields

What your integration should do

1. Poll /status.
2. If failure.status is refund_pending or refund_succeeded, treat it as a refund. Do not ask the user to sign a transaction.
3. If failure.status is manual_action_required, continue polling. 0x submits the destination retry unless the bridge is CCIP. Do not ask the user to sign a transaction.
4. If failure.status is failed, contact 0x support with the zid from /status.

Refund Token and Chain

The refund token and chain depend on where the failure happened and what the route looked like. The refund is not always in the user’s original sellToken on originChain. What you get back depends on the bridge (see table below) and the route composition.

The main thing to understand: the refund token is based on the bridge step’s sell or buy token and not the route’s sellToken. If the route included a swap or wrap before the bridge, the bridge step’s tokens differ from what the user started with:

The recovery.token, recovery.chainId, and recovery.amount fields contain the exact details. For destination retries, these fields describe delivery on the destination chain, not an origin refund.

Tracking Refund Progress

For automatic refunds, keep polling /status:

1. bridge_failed + refund_pending - refund initiated
2. bridge_failed + refund_succeeded - refund confirmed, failure.transactions has refund tx hash and recovery.settledAmount has actual refunded amount

Tracking Dest Retry Progress

For destination retries submitted by 0x, continue polling /status:

1. When the top-level status is bridge_failed and failure.status is manual_action_required, the destination retry is in progress. manualTransaction is null. Retry transaction hashes may appear in failure.transactions and the top-level transactions array before they are mined. A transaction hash does not mean that recovery is complete.
2. When the retry succeeds, the top-level status changes to bridge_filled and the failure object is removed.
3. If failure.status remains manual_action_required, the destination retry has not completed. Only Arbitrum Bridge can move to failed after deadline.

Recovery Behavior by Bridge

In this table, “bridge step’s sell/buy token” refers to the tokens on the bridge step specifically - not the user’s original sellToken/buyToken from the quote request. If the route included a swap or wrap before the bridge, these are different. See Refund Token and Chain above.

For bridges marked “Not tracked”, the 0x status service does not track the recovery process. The bridge provider may still offer recovery through their own tools.

Example: Automatic Refund (Across)

{
  "failure": {
    "reason": "expired", "status": "refund_pending",
    "recovery": { "chainId": 8453, "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "2500000000", "estimatedTimeSeconds": 1200 }
  }
}

Example: Dest Retry in Progress (Stargate)

A Stargate transfer to Arbitrum (chain 42161) ran out of gas while executing on the destination chain. 0x submits a recovery transaction to retry the destination call, so manualTransaction is null. Recovery transaction hashes can appear in transactions while status remains bridge_failed. Keep polling until the status changes to bridge_filled.

{
  "failure": {
    "reason": "out_of_gas", "status": "manual_action_required",
    "recovery": { "chainId": 42161, "token": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", "amount": "2500000000",
      "manualTransaction": null }
  }
}

Example: Arbitrum Bridge Deadline

0x retries the recovery transaction a few times, but does not keep retrying until deadline. The user does not need to sign or submit the recovery transaction.

{
  "failure": {
    "reason": "out_of_gas", "status": "manual_action_required",
    "recovery": { "chainId": 42161, "deadline": 1713000000, "manualTransaction": null }
  }
}