Links

Transactions APIs

1. Create Transaction

When a user starts swapping or when a step of swap succeeds, to get the transaction for the next step, this endpoint should be called.
In multi-step swaps created by Rango, you should loop over the routeResponse.route array and call createTransaction per each step.
post
https://api.rango.exchange:443
/tx/create
Creates a Cosmos/EVM/Transfer transaction
Typescript
cURL
const transaction = await rangoClient.createTransaction({
requestId: bestRoute.requestId,
step: 1,
userSettings: { 'slippage': '1' },
validations: { balance: true, fee: true },
})
curl 'https://api.rango.exchange/tx/create?apiKey=YOUR_API_KEY' \
-H 'content-type: application/json;charset=UTF-8' \
--data-raw '{"requestId":"BEST ROUTE REQUEST ID","step":1,"userSettings":{"slippage":"1.0"},"validations":{"balance":true,"fee":true}}' \
--compressed
A single route step might need multiple approvals (e.g. in Harmony Bridge), so you should call createTransaction and check approval again and again until isApprovalTx field turns to false.
In general, always check your code with a new token that your wallet has not already approved to make sure your approval scenario works well

Create Transaction Request

Param
Description
requestId *
The unique ID which is generated in the best route endpoint.
step *
1-based step number of a complex multi-step swap, e.g. 1, 2, ...
userSettings *
User settings for the swap, including slippage.
validations
The validation checks we are interested to check by Rango before starting the swap.

Create Transaction Response

Field
Description
ok
If true, Rango has created a non-null transaction, and the error message is null.
error
Error message about the incident if ok == false.
transaction
Transaction's raw data. It is one of the transaction possible interfaces: EvmTransaction, CosmosTransaction and TransferTransaction or null.

2. Check Transaction Status

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.
post
https://api.rango.exchange:443
/tx/check-status
Check if the signed transaction of user has succeeded or not
Typescript
cURL
const transaction = await rangoClient.checkStatus({
requestId: bestRoute.requestId,
step: 1,
txId: 'TX HASH RETUREN BY WALLET',
})
curl 'https://api.rango.exchange/tx/check-status?apiKey=YOUR_API_KEY' \
-H 'content-type: application/json;charset=UTF-8' \
--data-raw '{"step":1,"txId":"TX HASH RETUREN BY WALLET","requestId":"BEST ROUTE REQUEST ID"}' \
--compressed
This endpoint is not determined for checking approval and only for the original transaction. In case of multiStepTx, where more than one transaction should be signed in a single step, txId should be the latest transaction signed by user.

Check Transaction Status Request

Param
Description
requestId *
The unique ID which is generated in the best route endpoint.
step *
1-based step number of a complex multi-step swap, e.g. 1, 2, ...
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.
timestamp
The timestamp of the executed transaction. Beware that timestamp can be null even if the status is successful or failed, e.g. 1635271424813
extraMessage
A message in case of failure, that could be shown to the user.
outputAmount
The output amount of the transaction if it was successful, e.g. 0.28.
newTx
if a transaction needs more than one-step transaction to be signed by the user, the next step transaction will be returned in this field.
diagnosisUrl
In some special cases (e.g. AnySwap), the user should follow some steps outside Rango to get its assets back (refund). You could show this link to the user to help him
explorerUrl
List of explorer URLs for the transactions that happened in this step.
referrals
List of referral reward for the dApp and Rango.
Use diagnosisUrl if it's not null to help user more easily refund a failed transaction.

3. Check Approval Status

When createTransaction returns an approval transaction, and the user signs that tx, you should periodically call check-approval to see if the approval tx is completed. After a successful check, you should call createTransaction again to receive the main transaction (or the next approval transaction).
get
https://api.rango.exchange:443
/tx/{requestId}/check-approval
Checking that a approve tx hash is approved on blockchain
Typescript
cURL
const transaction = await rangoClient.checkApproval({
requestId: bestRoute.requestId
})
curl 'https://api.rango.exchange/{requestId}/check-approval?apiKey=YOUR_API_KEY'
If the result of createTransaction is an approval transaction, you should use this function to check the approval status instead of checkStatus.

Check Approval Request

Param
Description
requestId *
The unique ID which is generated in the best route endpoint.

Check Approval Response

Field
Description
isApproved
A flag that indicates that the approval tx is done or not.

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.
post
https://api.rango.exchange:443
/tx/report-tx
Report cancellation of a swap by UI to server
Typescript
cURL
const transaction = await rangoClient.reportFailure({
requestId: bestRoute.requestId,
eventType: 'TX_FAIL',
data: {
extraMessage: "Error sending transaction",
extraMessageDetail: "User Denied",
eventType: "smart_contract_call_failed"
}
})
curl 'https://api.rango.exchange/tx/report-tx?apiKey=YOUR_API_KEY' \
-H 'content-type: application/json;charset=UTF-8' \
--data-raw '{"requestId":"BEST ROUTE REQUEST ID","eventType":"TX_FAIL","data":{"extraMessage":"Error sending transaction","extraMessageDetail":"User Denied","eventType":"smart_contract_call_failed"}}' \
--compressed
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 *
TX_FAIL
data *
Failure reason