Links

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:

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.
Typescript
cURL
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'
Check TX Status
rango-exchange
Check Transaction Status Swagger
  • 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...

Check Transaction Status Response

Field
Description
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.
Typescript
cURL
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: */*'
Check Approval TX Status
rango-exchange
Check Approval Transaction Status Swagger
You could stop checking approval endpoint if:
  1. 1.
    Approval transaction succeeded. => isApproved === true
  2. 2.
    Approval transaction failed. => !isApproved && txStatus === 'failed'
  3. 3.
    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...

Check Approval Response

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
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.
Typescript
cURL
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."
}
'
Report Failed TX
rango-exchange
Report TX Failure Swagger
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
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.