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.

Creates a Cosmos/EVM/Transfer transaction

When user starts swapping or when a step of swap succeeds, to get the transaction for the next step, this endpoint should be called

POSThttps://api.rango.exchange:443/tx/create

Query parameters

Body

application/json

requestIdstring

Unique requestId received from bestRoute endpoint

stepinteger (int32)

Number of current step, starting from 1

userSettingsUserSettings

Settings of user for swaps

validationsCreateTransactionValidation

List of validations that Rango should do

Response

200201401403404

OK

Body

*/*

errorstring

Error message about the incident if ok == false

okboolean

If true, Rango has created a non-null transaction and error message is null

transactionGenericTransaction

Transaction's raw data

Request

JavaScriptCurl

const response = await fetch('https://api.rango.exchange:443/tx/create', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

{
  "error": "text",
  "ok": false,
  "transaction": {
    "type": "COSMOS"
  }
}

Typescript

const transaction = await rangoClient.createTransaction({
    requestId: bestRoute.requestId,
    step: 1,
    userSettings: { 'slippage': '1' },
    validations: { balance: true, fee: true },
})

cURL

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.

Check if the signed transaction of user has succeeded or not

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

POSThttps://api.rango.exchange:443/tx/check-status

Query parameters

Body

application/json

requestIdstring

The unique ID generate in best route endpoint

stepinteger (int32)

1-based step number of a complex multi-step swap

txIdstring

Tx id that wallet returned

Response

200201401403404

OK

Body

*/*

diagnosisUrlstring

In some special cases [ex: AnySwap], user should follow some steps outside Rango to get its assets. You can show this to user as help

explorerUrlarray of ExplorerUrl

List of explorer urls for the transactions that happened in this step.

extraMessagestring

A message in case of failure, that can be shown to user

newTxGenericTransaction

Transaction's raw data

outputAmountnumber (bigdecimal)

The output amount of the transaction if it was successful

referralsarray of TransactionStatusReferral

List of referral reward for the dApp and Rango

statusenum

Status of the transaction, while the status is running, client should retry the check status

failedrunningsuccess

timestampinteger (int64)

The timestamp of the executed transaction. Beware that timestamp can be null even if the status is successful or failed

Request

JavaScriptCurl

const response = await fetch('https://api.rango.exchange:443/tx/check-status', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

{
  "diagnosisUrl": "null",
  "explorerUrl": [
    {
      "description": "Inbound",
      "url": "https://etherscan.io/tx/0xa1a37ce2063c4764da27d990a22a0c89ed8ac585286a77aa02e1c1998203de19"
    }
  ],
  "extraMessage": "text",
  "newTx": {
    "type": "COSMOS"
  },
  "outputAmount": 0.28,
  "referrals": [
    {
      "address": "0x3ee2200efb3400fabb9aacf31297cbdd1d435d47",
      "amount": 1000000000000000000,
      "blockChain": "BSC",
      "decimals": 18,
      "symbol": "ADA"
    }
  ],
  "status": "success",
  "timestamp": 1635271424813
}

Typescript

const transaction = await rangoClient.checkStatus({
    requestId: bestRoute.requestId,
    step: 1,
    txId: 'TX HASH RETUREN BY WALLET',
})

cURL

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).

Checking that a approve tx hash is approved on blockchain

When createTransaction returns an approve transaction, and 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.

GEThttps://api.rango.exchange:443/tx/{requestId}/check-approval

Path parameters

request*string

unique ID generated by best route endpoint

Query parameters

Response

200400403429500

OK

Body

*/*

isApprovedboolean

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

Request

JavaScriptCurl

const response = await fetch('https://api.rango.exchange:443/tx/{requestId}/check-approval', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "isApproved": true
}

Typescript

const transaction = await rangoClient.checkApproval({
    requestId: bestRoute.requestId
})

cURL

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.

Report cancellation of a swap by UI to server

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

POSThttps://api.rango.exchange:443/tx/report-tx

Query parameters

Body

application/json

dataobject

A list of key-value for extra details

eventTypeenum

Type of the event that happened

TX_FAIL

requestIdstring

requestId from best route endpoint

Response

200201401403404

OK

Request

JavaScriptCurl

const response = await fetch('https://api.rango.exchange:443/tx/report-tx', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Typescript

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

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