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.
The result will look similar to the following:
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 unavailableREFUND_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 likeacross
,hop
,stargate
oramarok
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:
Last updated