Status of a Transaction

Checking if a cross-chain transfer is completed.

The full API documentation for our /status endpoint can be found here.

The status of a transaction can also be checked online via our Transaction Explorer

A link to the explorer is returned in the lifiExplorerLink attribute with each status call.

If you have looked at our Transferring Tokens Guide, you know how to request and submit a transaction.

To fetch the execution status of a transfer, the /status endpoint can be queried.

The txHash needs to be set, and the fromChain, toChain, and bridge parameters are optional. API will help to calculate other missing parameters and tell whether the transaction is a cross-chain transfer or a simple swap

While none of the parameters fromChain, toChain and bridge are required, passing the fromChain parameter will speed up the request and is therefore encouraged.

If you are willing to provide all parameters for swaps, please note that the fromChain and toChain have to be set to the same value. The bridge parameter can be omitted.

const getStatus = async (txHash) => {
    const result = await axios.get('https://li.quest/v1/status', {
        params: {
            txHash,
        }
    });
    return result.data;
}

The result will look similar to the following:

{
  "transactionId": "0x0959ee0fbb37a868752d7ae40b25dbfa3b7d72f499fa8386fd5f4105b18b62bd",
  "sending": {
    "txHash": "0x5862726dbc6643c6a34b3496bb15e91f11771f6756ccf83826304846bbc93c0v",
    "txLink": "https://etherscan.io/tx/0x5862726dbc6643c6a34b3496bb15e91f11771f6756ccf83826304846bbc93c0v",
    "amount": "60000000000000000000000",
    "token": {
      "address": "0x8AB2ff0116A279a99950C66A12298962D152B83c",
      "chainId": 1,
      "symbol": "ORDS",
      "decimals": 18,
      "name": "Ordiswap",
      "coinKey": "ORDS",
      "logoURI": "https://static.debank.com/image/eth_token/logo_url/0x8ab2ff0116a279a99950c66a12298962d152b83c/26147df2b81ff52d0545e98147a31268.png",
      "priceUSD": "0.012027801612559667"
    },
    "chainId": 1,
    "gasPrice": "23079962248",
    "gasUsed": "231727",
    "gasToken": {
      "address": "0x0000000000000000000000000000000000000000",
      "chainId": 1,
      "symbol": "ETH",
      "decimals": 18,
      "name": "ETH",
      "coinKey": "ETH",
      "logoURI": "https://raw.githubusercontent.com/trustwallet/assets/master/blockchains/ethereum/assets/0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2/logo.png",
      "priceUSD": "2623.22"
    },
    "gasAmount": "5348250411842296",
    "gasAmountUSD": "14.0296",
    "amountUSD": "721.6681",
    "value": "0",
    "includedSteps": [
      {
        "tool": "feeCollection",
        "toolDetails": {
          "key": "feeCollection",
          "name": "Integrator Fee",
          "logoURI": "https://raw.githubusercontent.com/lifinance/types/main/src/assets/icons/protocols/feeCollection.png"
        },
        "fromAmount": "60000000000000000000000",
        "fromToken": {
          "address": "0x8AB2ff0116A279a99950C66A12298962D152B83c",
          "chainId": 1,
          "symbol": "ORDS",
          "decimals": 18,
          "name": "Ordiswap",
          "coinKey": "ORDS",
          "logoURI": "https://static.debank.com/image/eth_token/logo_url/0x8ab2ff0116a279a99950c66a12298962d152b83c/26147df2b81ff52d0545e98147a31268.png",
          "priceUSD": "0.012027801612559667"
        },
        "toToken": {
          "address": "0x8AB2ff0116A279a99950C66A12298962D152B83c",
          "chainId": 1,
          "symbol": "ORDS",
          "decimals": 18,
          "name": "Ordiswap",
          "coinKey": "ORDS",
          "logoURI": "https://static.debank.com/image/eth_token/logo_url/0x8ab2ff0116a279a99950c66a12298962d152b83c/26147df2b81ff52d0545e98147a31268.png",
          "priceUSD": "0.012027801612559667"
        },
        "toAmount": "59820000000000000000000"
      },
      {
        "tool": "1inch",
        "toolDetails": {
          "key": "1inch",
          "name": "1inch",
          "logoURI": "https://raw.githubusercontent.com/lifinance/types/main/src/assets/icons/exchanges/oneinch.png",
          "webUrl": "https://app.1inch.io/"
        },
        "fromAmount": "59820000000000000000000",
        "fromToken": {
          "address": "0x8AB2ff0116A279a99950C66A12298962D152B83c",
          "chainId": 1,
          "symbol": "ORDS",
          "decimals": 18,
          "name": "Ordiswap",
          "coinKey": "ORDS",
          "logoURI": "https://static.debank.com/image/eth_token/logo_url/0x8ab2ff0116a279a99950c66a12298962d152b83c/26147df2b81ff52d0545e98147a31268.png",
          "priceUSD": "0.012027801612559667"
        },
        "toToken": {
          "address": "0x0000000000000000000000000000000000000000",
          "chainId": 1,
          "symbol": "ETH",
          "decimals": 18,
          "name": "ETH",
          "coinKey": "ETH",
          "logoURI": "https://raw.githubusercontent.com/trustwallet/assets/master/blockchains/ethereum/assets/0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2/logo.png",
          "priceUSD": "2623.22"
        },
        "toAmount": "275101169247651913",
        "bridgedAmount": null
      }
    ],
    "timestamp": 1727267627
  },
  "receiving": {
    "txHash": "0x2862726dbc6643c6a34b3496bb15e91f11771f6756ccf83826604846bbc93c0v",
    "txLink": "https://etherscan.io/tx/0x2862726dbc6643c6a34b3496bb15e91f11771f6756ccf83826604846bbc93c0v",
    "amount": "275101169247651913",
    "token": {
      "address": "0x0000000000000000000000000000000000000000",
      "chainId": 1,
      "symbol": "ETH",
      "decimals": 18,
      "name": "ETH",
      "coinKey": "ETH",
      "logoURI": "https://raw.githubusercontent.com/trustwallet/assets/master/blockchains/ethereum/assets/0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2/logo.png",
      "priceUSD": "2623.22"
    },
    "chainId": 1,
    "gasPrice": "23079962248",
    "gasUsed": "231727",
    "gasToken": {
      "address": "0x0000000000000000000000000000000000000000",
      "chainId": 1,
      "symbol": "ETH",
      "decimals": 18,
      "name": "ETH",
      "coinKey": "ETH",
      "logoURI": "https://raw.githubusercontent.com/trustwallet/assets/master/blockchains/ethereum/assets/0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2/logo.png",
      "priceUSD": "2623.22"
    },
    "gasAmount": "5348250411842296",
    "gasAmountUSD": "14.0296",
    "amountUSD": "721.6509",
    "value": "0",
    "timestamp": 1727267627
  },
  "lifiExplorerLink": "https://scan.li.fi/tx/0x5862726dbc6643c6a34b3496bb15e91f11771f6756ccf83826304846bbc93c0v",
  "fromAddress": "0x14a980237fa9797fa27c5152c496cab65e36da4f",
  "toAddress": "0x14a980237fa9797fa27c5152c496cab65e36da4f",
  "tool": "1inch",
  "status": "DONE",
  "substatus": "COMPLETED",
  "substatusMessage": "The transfer is complete.",
  "metadata": {
    "integrator": "example_integrator"
  }
}

The different statuses and what they mean

The response from our /status endpoint contains the property status, indicating the current state of the transaction. The possible values are NOT_FOUND, INVALID, PENDING, DONE, or FAILED.

NOT_FOUND: This means that the transaction doesn't exist. This can happen if the passed hash refers to a transaction that has yet to be mined.
INVALID The provided transaction hash does not seem to be tied to the tool you requested the status from. This can happen if the status monitoring is requested for 'connext', but the transaction was processed through 'hop'.
PENDING: The initial transaction was mined, but the bridging process is still in progress. You can also get this status if part of the third-party services we rely on is unreachable or the RPC communication isn't working correctly. Please take a look at the sub-status to know more.
DONE: The final transaction was received on the destination chain, and the operation has concluded. The sub-status will indicate whether there has been a refund or if the tokens received were only partially delivered.
FAILED: The bridging transaction was marked as failed. Look into the transactions to learn what exactly went wrong.

The different sub-statuses and what they mean

When the status is either DONE, FAILED or PENDING, we also return a sub-status to explain the situation better.

Sub-statuses of PENDING:

WAIT_SOURCE_CONFIRMATIONS: The bridge is waiting for additional confirmations.
WAIT_DESTINATION_TRANSACTION: The off-chain logic is in progress, waiting for the destination transaction to be mined. Check back later.
BRIDGE_NOT_AVAILABLE: The bridge API / subgraph is temporarily unavailable; check back later.
CHAIN_NOT_AVAILABLE: The RPC for the source/destination chain is temporarily unavailable
REFUND_IN_PROGRESS: The refund has been requested, and it's being processed (not all bridges will go through this state!)
UNKNOWN_ERROR: We cannot determine the status of the transfer.

Sub-statuses of DONE:

COMPLETED: The transfer was successful.
PARTIAL: The transfer was partially successful. This can happen for specific bridges like across , hop, stargate or amarok which may provide alternative tokens in case of low liquidity.
REFUNDED: The transfer was not successful, and the sent token has been refunded

Sub-status of FAILED:

NOT_PROCESSABLE_REFUND_NEEDED: The transfer cannot be completed; a refund is required.
OUT_OF_GAS: The transaction ran out of gas during execution.
SLIPPAGE_EXCEEDED: The return amount is not enough. This can occur when the slippage limit is exceeded.
INSUFFICIENT_ALLOWANCE: Transfer amount exceeds allowance (insufficient allowance).
INSUFFICIENT_BALANCE: Transfer amount exceeds balance.
UNKNOWN_ERROR: An unknown error occurred, or an invalid amount was sent. This can include errors like InvalidAmount, ORACLE_NOT_FEASIBLE, LayerZero: not enough native for fees, and more.
EXPIRED: The transaction expired before it could be processed.

Handling unexpected receiving token

REFUNDED: The transfer was not successful, and the sent token has been refunded

When using amarok or hop it can happen that receiving.token is not the token requested in the original quote:

amarok mints custom nextToken when bridging and swap them automatically to the token representation the user requested. In rare cases, it can happen that while the transfer was executed, the swap liquidity to exchange that token was used up. In this case, the user receives the nextToken instead. You can go to this webpage to exchange that token later.
hop mints custom hToken when bridging and swap them automatically to the token representation the user requested. In rare cases, it can happen that while the transfer was executed, the swap liquidity to exchange that token was used up. In this case, the user receives the nextToken instead. You can go to this webpage to exchange that token later.

Querying the status endpoint

If your dApp wants to wait for the completion of the cross-chain transfer, it can query the /status endpoint until a final state is reached:

const getStatus = async (txHash) => {
    const result = await axios.get('https://li.quest/v1/status', {
        params: {
            txHash,
        }
    });
    return result.data;
}

let result;
do {
    result = await getStatus(tx.hash);
} while (result.status !== 'DONE' && result.status !== 'FAILED')

console.log(`Transfer completed with state ${result.status}`);

Last updated 7 months ago

Was this helpful?