Transactions APIs

1. Create Transaction (Test)

In the Basic API, you could get the transaction via swap endpoint (the tx field). Please check this link for more information on this:

pageQuote & Swap APIs

2. Check Transaction Status (Test)

After that user signed a transaction on his/her wallet you should call this endpoint periodically to see what's the status of that transaction.

const transaction = await rangoClient.status({
    requestId: swapResponse.requestId,
    txId: 'TX HASH RETURENED BY WALLET',
})

curl --request GET \
     --url 'https://api.rango.exchange/basic/status?requestId=b3a12c6d-86b8-4c21-97e4-809151dd4036&txId=0xfa88b705a5b4049adac7caff50c887d9600ef023ef1a937f8f8b6f44e90042b5&apiKey=c6381a79-2817-4602-83bf-6a641a409e32'

This endpoint is not suitable for checking approval tx and it is only for the original transaction. For checking approval transaction status, please check this section.
In on-chain transactions, you could also check transaction status by checking transaction receipt (via RPC) if you prefer. But in cross-chain swaps (bridges, ...) it's necessary to use this endpoint to make sure outbound transaction (transaction on destination chain) succeeeds without any problem.

Check Transaction Status Request

Param	Description
requestId *	The unique ID which is generated in the swap endpoint.
txId *	Tx hash that wallet returned, e.g. 0xa1a37ce2063c4764da27d990a22a0c89ed8...

Param

Description

requestId *

The unique ID which is generated in the swap endpoint.

txId *

Tx hash that wallet returned, e.g. 0xa1a37ce2063c4764da27d990a22a0c89ed8...

Check Transaction Status Response

Field Description

Field	Description
status	Status of the transaction, while the status is `running` (or `null`), the client should retry until it turns into `success` or`failed`.
error	A message in case of failure, that could be shown to the user.
output	The output asset and amount, could be different from the destination asset in case of failures and refunds. These are different output types possible: `'REVERTED_TO_INPUT' \| 'MIDDLE_ASSET_IN_SRC' \| 'MIDDLE_ASSET_IN_DEST' \| 'DESIRED_OUTPUT'`
explorerUrl	List of explorer URLs for the transactions of this swap. (Inbound TX link, Outbound TX link, ...)
diagnosisUrl	If a refund is needed for the swap, we will return a diagnosis URL for the user. This URL will guide him on how to refund his/her money. Sample value: https://rango.exchange/diagnosis/wormhole
bridgeData	Status of bridge. At the moment, this field is only filled when we have a bridge/swap transaction between two EVM chains. (e.g. from Polygon to Avax)

status

Status of the transaction, while the status is running (or null), the client should retry until it turns into success orfailed.

error

A message in case of failure, that could be shown to the user.

output

The output asset and amount, could be different from the destination asset in case of failures and refunds. These are different output types possible: 'REVERTED_TO_INPUT' | 'MIDDLE_ASSET_IN_SRC' | 'MIDDLE_ASSET_IN_DEST' | 'DESIRED_OUTPUT'

explorerUrl

List of explorer URLs for the transactions of this swap. (Inbound TX link, Outbound TX link, ...)

diagnosisUrl

If a refund is needed for the swap, we will return a diagnosis URL for the user. This URL will guide him on how to refund his/her money. Sample value: https://rango.exchange/diagnosis/wormhole

bridgeData

Status of bridge. At the moment, this field is only filled when we have a bridge/swap transaction between two EVM chains. (e.g. from Polygon to Avax)

Sample Response

{
    "status": "success",
    "error": null,
    "diagnosisUrl": null,
    "explorerUrl": [
        {
            "url": "https://bscscan.com/tx/0xe5c7ec65ca86a80b5f92c9c2d9854c4f775cb1ae4b06f22dc54e7eec3078ac9e",
            "description": "Inbound"
        },
        {
            "url": "https://polygonscan.com/tx/0xa2dc3186b9134ec649ede0c9676dfe0826563a05cfb355bdbc51841b47818da3",
            "description": "Outbound"
            }
    ],
    "output": {
            "amount": "18310000",
            "receivedToken": {
                    "blockchain": "POLYGON",
                    "symbol": "USDT",
                    "name": null,
                    "isPopular": false,
                    "chainId": "137",
                    "address": "0xc2132d05d31c914a87c6611c10748aeb04b58e8f",
                    "decimals": 6,
                    "image": "https://api.rango.exchange/tokens/ETH/USDT.png",
                    "blockchainImage": "https://api.rango.exchange/blockchains/polygon.svg",
                    "usdPrice": null,
                    "supportedSwappers": []
            },
            "type": "DESIRED_OUTPUT"
    },
    "bridgeData": {
            "srcChainId": 56,
            "srcTxHash": "0xe5c7ec65ca86a80b5f92c9c2d9854c4f775cb1ae4b06f22dc54e7eec3078ac9e",
            "srcToken": "0x55d398326f99059ff775485246999027b3197955",
            "srcTokenAmt": "18500000000000000000",
            "srcTokenDecimals": 18,
            "srcTokenPrice": "0.999969",
            "destChainId": 137,
            "destTxHash": "0xa2dc3186b9134ec649ede0c9676dfe0826563a05cfb355bdbc51841b47818da3",
            "destToken": "0xc2132d05d31c914a87c6611c10748aeb04b58e8f",
            "destTokenDecimals": 6,
            "destTokenAmt": "18310000",
            "destTokenPrice": "0.999969"
    }
}

3. Check Approval Status (Test)

In EVM, TRON and STARKNET txType blockchains where swap returns a non-null value for approve tx (e.g. approveData and approveTo fields in case of the EVM), you need to use these values to show approve transaction to the user and call isApproved periodically to see if the approval tx is completed. After a successful check, you should create the main transaction.

Notice:

It is important to use approve transaction data generated by Rango API and not hard-coding something on your client side for creating approve transaction, because for some protocols (some bridges), the contract that should be approved is dynamically generated via their API based on route.

For checking approval transaction status, you could check it directly from the RPC endpoint if you prefer and skip calling Rango API for this purpose.

const transaction = await rangoClient.isApproved(
    requestId = bestRoute.requestId,
    txId = 'APPROVE TX HASH RETURENED BY WALLET
)

curl --request GET \
     --url 'https://api.rango.exchange/basic/is-approved?requestId=e4b0d1e7-ae1f-4aed-ab91-f1ea3ba9383b&txId=0xd7a18c6e2f9afe5aefd1b5969f753513f01c6670a4fc57a2d1349ad539ae2f7f&apiKey=c6381a79-2817-4602-83bf-6a641a409e32' \
     --header 'accept: */*'

You could stop checking approval endpoint if:

Approval transaction succeeded. => isApproved === true
Approval transaction failed. => !isApproved && txStatus === 'failed'
Approval transaction succeeded but currentApprovedAmount is still less than requiredApprovedAmount (e.g. user changed transaction data and enter another approve amount in MetaMask instead of default approve amount proposed by Rango API) => !isApproved && txStatus === 'success'

Check Approval Request

Param	Description
requestId *	The unique ID which is generated in the best route endpoint.
txId *	Tx hash that wallet returned for approve tx, e.g. 0xa1a37ce2063c4764da27d990a22a0c89ed8...

Param

Description

requestId *

The unique ID which is generated in the best route endpoint.

txId *

Tx hash that wallet returned for approve tx, e.g. 0xa1a37ce2063c4764da27d990a22a0c89ed8...

Check Approval Response

Field Description

Field	Description
isApproved	A flag which indicates that the approve tx is done or not.
txStatus	Status of approve transaction in blockchain (possible values are `success`, `running` and `failed`) if `isArppoved` is false and `txStatus` is failed, it means that approve transaction is failed in the blockchain.
requiredApprovedAmount	Required amount to be approved by user
currentApprovedAmount	Current approved amount by user

isApproved

A flag which indicates that the approve tx is done or not.

txStatus

Status of approve transaction in blockchain (possible values are success, running and failed)

if isArppoved is false and txStatus is failed, it means that approve transaction is failed in the blockchain.

requiredApprovedAmount

Required amount to be approved by user

currentApprovedAmount

Current approved amount by user

Sample Response

{
    "isApproved": true,
    "txStatus": "success",
    "currentApprovedAmount": "0.903658",
    "requiredApprovedAmount": "0.903658"
}

4. Report Transaction Failure

Use it when the user rejects the transaction in the wallet or the wallet fails to handle the transaction. Calling this endpoint is not required, but is useful for reporting and we recommend calling it.

const transaction = await rangoClient.reportFailure({
    requestId: swapResponse.requestId, // e.g. 2823418f-9e18-4110-8d36-b569b0af025e
    eventType: 'SEND_TX_FAILED',
    step: 1,
    reason: 'Transaction is underpriced.'
})

curl --request POST \
     --url 'https://api.rango.exchange/basic/report-tx?apiKey=c6381a79-2817-4602-83bf-6a641a409e32' \
     --header 'content-type: application/json' \
     --data '
{
  "requestId": "2823418f-9e18-4110-8d36-b569b0af025e",
  "eventType": "SEND_TX_FAILED",
  "step": 1,
  "reason": "Transaction is underpriced."
}
'

It's an optional action and does not affect the flow of swap, but it can help us improve our API if the data is informative enough

Report Failure Request

Param Description

Param	Description
requestId *	The unique ID which is generated in the best route endpoint.
eventType *	Type of failure. possible values are: `FETCH_TX_FAILED, USER_REJECT, USER_CANCEL, CALL_WALLET_FAILED, SEND_TX_FAILED, CLIENT_UNEXPECTED_BEHAVIOUR, TX_EXPIRED, INSUFFICIENT_APPROVE`
reason *	Failure reason
tags	An optional dictionary of pre-defined tags. Current allowed tags are `wallet` and `errorCode`.

requestId *

The unique ID which is generated in the best route endpoint.

eventType *

Type of failure. possible values are:

FETCH_TX_FAILED, USER_REJECT, USER_CANCEL, CALL_WALLET_FAILED, SEND_TX_FAILED, CLIENT_UNEXPECTED_BEHAVIOUR, TX_EXPIRED, INSUFFICIENT_APPROVE

reason *

Failure reason