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.

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.

Failure Object Structure

1
{
2
  "status": "bridge_failed",
3
  "bridge": "across_v4",
4
  "failure": {
5
    "reason": "expired",
6
    "status": "refund_pending",
7
    "transactions": [
8
      { "chainId": 8453, "txHash": "0xabc...", "timestamp": 1712345678 }
9
    ],
10
    "recovery": {
11
      "chainId": 8453,
12
      "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
13
      "amount": "2500000000",
14
      "estimatedTimeSeconds": 1200,
15
      "deadline": null,
16
      "manualTransaction": null,
17
      "settledAmount": null
18
    }
19
  }
20
}

Failure Reasons

Failure Statuses

Recovery Step Fields

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 refund details.

Manual Recovery Transactions

When manualTransaction is present, it’s a complete transaction.

EVM:

1
{ "chainType": "evm", "to": "0x...", "data": "0x...", "value": "0", "gas": "200000", "gasPrice": "30000000000" }

Submit via eth_sendTransaction on chain recovery.chainId.

Solana:

1
{ "chainType": "svm", "serializedTransaction": "<base64>" }

Base64-decode, sign, submit.

• Can be submitted by anyone, not just the original sender
• If deadline is set, submit before it expires as otherwise funds might be lost

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

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. Contact 0x support with the zid for assistance.

Example: Automatic Refund (Across)

1
{
2
  "failure": {
3
    "reason": "expired", "status": "refund_pending",
4
    "recovery": { "chainId": 8453, "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "2500000000", "estimatedTimeSeconds": 1200 }
5
  }
6
}

Example: Manual Recovery with Transaction (Stargate)

A Stargate bridge delivering to Arbitrum (chain 42161) ran out of gas on destination:

1
{
2
  "failure": {
3
    "reason": "out_of_gas", "status": "manual_action_required",
4
    "recovery": { "chainId": 42161, "token": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", "amount": "2500000000",
5
      "manualTransaction": { "chainType": "evm", "to": "0x...", "data": "0x...", "value": "0", "gas": "150000", "gasPrice": "100000000" } }
6
  }
7
}

Example: Arbitrum Bridge Deadline

1
{
2
  "failure": {
3
    "reason": "out_of_gas", "status": "manual_action_required",
4
    "recovery": { "chainId": 42161, "deadline": 1713000000,
5
      "manualTransaction": { "chainType": "evm", "to": "0x...", "data": "0x...", "value": "0", "gas": "200000", "gasPrice": "100000000" } }
6
  }
7
}