SWAP Token Pairs
This guide will explain how to SWAP tokens using the Wallet-API.
SWAP Flow
Currently, the SWAP endpoints support the following chains:
- Ethereum
- Arbitrum
- Vechain
- Polygon (Matic)
- BSC (Binance Smart Chain).
The first step is to get a list of all the supported token pairs. The result varies according to the blockchain on which the wallet (
walletId) is hosted.If you feel you are missing a token pair, please contact us and we will look into making that available for you.
The token pairs will be automatically filtered based on the blockchain that is hosting the wallet. If the wallet is on Ethereum, the list will only display tokens that are available for swapping on the Ethereum blockchain.
Call the following endpoint to get SWAP pairs:
{id} : This is the
walletId. The SWAP pairs will be displayed based on the blockchain of this wallet.The wallet in this example is created on the MATIC blockchain.
{
"success": true,
"result": [
{
"from": {
"secretType": "MATIC",
"symbol": "MATIC",
"tokenAddress": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee"
},
"to": {
"secretType": "MATIC",
"symbol": "USDT",
"tokenAddress": "0xc2132d05d31c914a87c6611c10748aeb04b58e8f"
}
},
{
"from": {
"secretType": "MATIC",
"symbol": "MATIC",
"tokenAddress": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee"
},
"to": {
"secretType": "MATIC",
"symbol": "AAVE",
"tokenAddress": "0xd6df932a45c0f255f85145f286ea0b292b21c90b"
}
}
]
}
Parameter | Description |
|---|---|
from | This object holds details about the source token you desire to swap for another, including it's blockchain, symbol, and token address. |
to | This object holds details about the destination token you desire to swap to, including it's blockchain, symbol, and token address. |
secretType | The blockchain on which the wallet exists, for example: MATIC. |
symbol | The symbol name of the token. |
tokenAddress | Token address is the location of the smart contract responsible for managing the balances of all token holders. |
Save the details of your desired token pair, as they will be used later in the guide.
Now you should have information about your desired swap pair. The next step is to calculate the exchange rate of the pair.
This endpoint returns information about the expected result of the swap. It provides the expected output amount, as well gives information about the slippage, and fee involved for that specific swap.
Parameter | Type | Required | Description |
|---|---|---|---|
fromSecretType | string | ✅ | The blockchain of source token. |
toSecretType | object | ✅ | The blockchain of destination token. |
fromToken | string | ✅ | The token address of the source token. (you can get this from response body of the previous step) |
toToken | string | ✅ | The token address of the destination token. (you can get this from response body of the previous step) |
amount | integer | ✅ | The amount of coins you want to swap. |
orderType | string | ✅ | The type of order, which is SELL. |
GET /api/swaps/rates?fromSecretType=MATIC&toSecretType=MATIC&fromToken=0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee&toToken=0x348e62131fce2f4e0d5ead3fe1719bc039b380a9&amount=1&orderType=SELL
{
"success": true,
"result": {
"exchangeRates": [
{
"exchange": "ONE_INCH",
"orderType": "SELL",
"inputAmount": 1.000000000000000000,
"outputAmount": 0.773096508478042589,
"slippage": 0.05,
"fee": 3.0
}
],
"bestRate": {
"exchange": "ONE_INCH",
"orderType": "SELL",
"inputAmount": 1.000000000000000000,
"outputAmount": 0.773096508478042589,
"slippage": 0.05,
"fee": 3.0
}
}
}
In the
result object you will find two more objects:exchangeRates: This will give you the exchange rate of a specific exchange.bestRate: This will give you the best exchange rate out of all the exchanges listed.
Parameters Explained:
Parameter | Description |
|---|---|
exchange | The name of the crypto exchanger. |
orderType | The type of order, for this case, it is SELL. |
inputAmount | The amount of source tokens you want to exchange. |
outputAmount | The expected amount of destination tokens that you will receive after the swap. |
slippage | The slippage percentage shows the difference between the expected outputAmount and the actual outputAmount. |
fee | Theis is the gas fee for the specific swap. |
Save the details of the
bestRate, as they will be used later in the guide.The next step is to build the swap transaction. The endpoint will return the transactions that are needed to perform the actual swap, based on information obtained from the previous, retrieve exchange rate endpoint.
This API endpoint will construct transactions for you. Subsequently, you or your user will be required to execute these transactions one by one.
{id} : This is the ID of the source wallet. (Wallet that holds tokens to swap)
Parameter | Type | Required | Description |
|---|---|---|---|
walletId | string | ✅ | ID of the source wallet. (Wallet that holds tokens to swap) |
destinationWalletId | string | ✅ | ID of the destination wallet. (Wallet that will receive the destination tokens) |
fromSecretType | string | ✅ | The blockchain of source token. |
toSecretType | string | ✅ | The blockchain of destination token. |
fromToken | string | ✅ | The token address of the source token. (you can get this from response body of the previous step) |
toToken | string | ✅ | The token address of the destination token. (you can get this from response body of the previous step) |
inputAmount | integer | ✅ | The amount of source tokens you want to exchange. |
outputAmount | integer | ✅ | The expected amount of destination tokens that you will receive after the swap. |
orderType | string | ✅ | The type of order, for this case, it is SELL. |
exchange | string | ✅ | The name of the crypto exchanger. |
enableGasEstimate | boolean | ✅ | Indicate to include gas estimate (response will contain value for the "gas" field). |
{
"walletId" : "b97e9e8b-035c-40a0-bac0-96b07fc0444a",
"destinationWalletId": "b97e9e8b-035c-40a0-bac0-96b07fc0444a",
"fromSecretType": "MATIC",
"toSecretType": "MATIC",
"fromToken": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
"toToken": "0xc2132d05d31c914a87c6611c10748aeb04b58e8f",
"inputAmount": "1",
"outputAmount": "2.038411",
"orderType": "SELL",
"exchange": "ONE_INCH",
"enableGasEstimate": true
}
{
"success": true,
"result": [
{
"walletId": "b97e9e8b-035c-40a0-bac0-96b07fc0444a",
"pincode": null,
"gasPrice": 20000000000,
"gas": 523381,
"nonce": null,
"value": 1000000000000000000,
"to": "0x11111112542d85b3ef69ae05771c2dccff4faa26",
"network": null,
"data": "0x7c0252000000000000000000000000000f85a912448279111694f4ba4f85dc641c54b59400000000000000000000000000000000000000000000000000000000000000600000000000000000000000000000000000000000000000000000000000000180000000000000000000000000eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee000000000000000000000000c2132d05d31c914a87c6611c10748aeb04b58e8f0000000000000000000000000f85a912448279111694f4ba4f85dc641c54b594000000000000000000000000150f50e0d321f4607d589f939a28c5f10b13d7b90000000000000000000000000000000000000000000000000de0b6b3a764000000000000000000000000000000000000000000000000000000000000001d66ab00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000008e00000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000000500000000000000000000000000000000000000000000000000000000000000a000000000000000000000000000000000000000000000000000000000000001c0000000000000000000000000000000000000000000000000000000000000028000000000000000000000000000000000000000000000000000000000000004e0000000000000000000000000000000000000000000000000000000000000064000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000800000000000000000000000000000000000000000000000000000000000000064d1660f99000000000000000000000000eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee0000000000000000000000001fb53eb183b86582176f6aa8f4db72b62caf0d4b000000000000000000000000000000000000000000000000006a94d74f430000000000000000000000000000000000000000000000000000000000000000000000000000000000000d500b1d8e8ef31e21c99d1db9a6444d3adf127000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000d7621dc5821000000000000000000000000000000000000000000000000000000000000000000800000000000000000000000000000000000000000000000000000000000000004d0e30db000000000000000000000000000000000000000000000000000000000800000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000001a4b3af37c0000000000000000000000000000000000000000000000000000000000000008080000000000000000000000000000000000000000000000000000000000000440000000000000000000000000d500b1d8e8ef31e21c99d1db9a6444d3adf1270000000000000000000000000000000500000000000000000000000000000005000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000800000000000000000000000000000000000000000000000000000000000000064d1660f990000000000000000000000000d500b1d8e8ef31e21c99d1db9a6444d3adf127000000000000000000000000055ff76bffc3cdd9d5fdbbc2ece4528ecce45047e00000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000800000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000000a4c9f12e9d00000000000000000000000055ff76bffc3cdd9d5fdbbc2ece4528ecce45047e0000000000000000000000000d500b1d8e8ef31e21c99d1db9a6444d3adf1270000000000000000000000000c2132d05d31c914a87c6611c10748aeb04b58e8f0000000000000000000000030f85a912448279111694f4ba4f85dc641c54b594000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000001a4b3af37c000000000000000000000000000000000000000000000000000000000000000808000000000000000000000000000000000000000000000000000000000000044000000000000000000000000c2132d05d31c914a87c6611c10748aeb04b58e8f000000000000000000000000000000010000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000800000000000000000000000000000000000000000000000000000000000000064d1660f99000000000000000000000000c2132d05d31c914a87c6611c10748aeb04b58e8f000000000000000000000000150f50e0d321f4607d589f939a28c5f10b13d7b900000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
"type": "MATIC_TRANSACTION"
}
]
}
This is the last step in the swap process. This step contains the transactions that will execute the swap.
From the previous endpoint, you get a response containing the transactions that need to be executed to complete the swap. The array of transactions need to be executed in the same order.
The reason why you might need to execute multiple transactions for a swap is because it might be necessary to approve a contract to spend tokens for executing a swap.
Next, you need to prepare all the transactions received from the previous response, under the
result array.The response from the previous call contains only 1 transaction that needs to be executed. As you can see, the
pincode is set to null. You will need to enrich this with the
pincode of that wallet.{
"success": true,
"result": [
{
"walletId": "b97e9e8b-035c-40a0-bac0-96b07fc0444a",
"pincode": null,
"gasPrice": 20000000000,
"gas": 523381,
"nonce": null,
"value": 1000000000000000000,
"to": "0x11111112542d85b3ef69ae05771c2dccff4faa26",
"network": null,
"data": "0x7c0252000000000000000000000000000f85a912448279111694f4ba4f85dc641c54b59400000000000000000000000000000000000000000000000000000000000000600000000000000000000000000000000000000000000000000000000000000180000000000000000000000000eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee000000000000000000000000c2132d05d31c914a87c6611c10748aeb04b58e8f0000000000000000000000000f85a912448279111694f4ba4f85dc641c54b594000000000000000000000000150f50e0d321f4607d589f939a28c5f10b13d7b90000000000000000000000000000000000000000000000000de0b6b3a764000000000000000000000000000000000000000000000000000000000000001d66ab00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000008e00000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000000500000000000000000000000000000000000000000000000000000000000000a000000000000000000000000000000000000000000000000000000000000001c0000000000000000000000000000000000000000000000000000000000000028000000000000000000000000000000000000000000000000000000000000004e0000000000000000000000000000000000000000000000000000000000000064000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000800000000000000000000000000000000000000000000000000000000000000064d1660f99000000000000000000000000eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee0000000000000000000000001fb53eb183b86582176f6aa8f4db72b62caf0d4b000000000000000000000000000000000000000000000000006a94d74f430000000000000000000000000000000000000000000000000000000000000000000000000000000000000d500b1d8e8ef31e21c99d1db9a6444d3adf127000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000d7621dc5821000000000000000000000000000000000000000000000000000000000000000000800000000000000000000000000000000000000000000000000000000000000004d0e30db000000000000000000000000000000000000000000000000000000000800000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000001a4b3af37c0000000000000000000000000000000000000000000000000000000000000008080000000000000000000000000000000000000000000000000000000000000440000000000000000000000000d500b1d8e8ef31e21c99d1db9a6444d3adf1270000000000000000000000000000000500000000000000000000000000000005000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000800000000000000000000000000000000000000000000000000000000000000064d1660f990000000000000000000000000d500b1d8e8ef31e21c99d1db9a6444d3adf127000000000000000000000000055ff76bffc3cdd9d5fdbbc2ece4528ecce45047e00000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000800000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000000a4c9f12e9d00000000000000000000000055ff76bffc3cdd9d5fdbbc2ece4528ecce45047e0000000000000000000000000d500b1d8e8ef31e21c99d1db9a6444d3adf1270000000000000000000000000c2132d05d31c914a87c6611c10748aeb04b58e8f0000000000000000000000030f85a912448279111694f4ba4f85dc641c54b594000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000001a4b3af37c000000000000000000000000000000000000000000000000000000000000000808000000000000000000000000000000000000000000000000000000000000044000000000000000000000000c2132d05d31c914a87c6611c10748aeb04b58e8f000000000000000000000000000000010000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000800000000000000000000000000000000000000000000000000000000000000064d1660f99000000000000000000000000c2132d05d31c914a87c6611c10748aeb04b58e8f000000000000000000000000150f50e0d321f4607d589f939a28c5f10b13d7b900000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
"type": "MATIC_TRANSACTION"
}
]
}
Don't forget to enrich the transactions with the correct
pincode.The final step is executing the transactions. Each item in the response array needs to be taken, enriched with the correct
pincode and submit against the following endpoint.Each transaction from the previous Build Swap Transaction's response body needs to be executed in the same order.
In our example, we only have one transaction, so we will add the
pincode and run it on the following endpoint.{
"walletId": "b97e9e8b-035c-40a0-bac0-96b07fc0444a",
"pincode": "123456",
"gasPrice": 20000000000,
"gas": 523381,
"nonce": null,
"value": 1000000000000000000,
"to": "0x11111112542d85b3ef69ae05771c2dccff4faa26",
"network": null,
"data": "0x7c0252000000000000000000000000000f85a912448279111694f4ba4f85dc641c54b59400000000000000000000000000000000000000000000000000000000000000600000000000000000000000000000000000000000000000000000000000000180000000000000000000000000eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee000000000000000000000000c2132d05d31c914a87c6611c10748aeb04b58e8f0000000000000000000000000f85a912448279111694f4ba4f85dc641c54b594000000000000000000000000150f50e0d321f4607d589f939a28c5f10b13d7b90000000000000000000000000000000000000000000000000de0b6b3a764000000000000000000000000000000000000000000000000000000000000001d66ab00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000008e00000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000000500000000000000000000000000000000000000000000000000000000000000a000000000000000000000000000000000000000000000000000000000000001c0000000000000000000000000000000000000000000000000000000000000028000000000000000000000000000000000000000000000000000000000000004e0000000000000000000000000000000000000000000000000000000000000064000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000800000000000000000000000000000000000000000000000000000000000000064d1660f99000000000000000000000000eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee0000000000000000000000001fb53eb183b86582176f6aa8f4db72b62caf0d4b000000000000000000000000000000000000000000000000006a94d74f430000000000000000000000000000000000000000000000000000000000000000000000000000000000000d500b1d8e8ef31e21c99d1db9a6444d3adf127000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000d7621dc5821000000000000000000000000000000000000000000000000000000000000000000800000000000000000000000000000000000000000000000000000000000000004d0e30db000000000000000000000000000000000000000000000000000000000800000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000001a4b3af37c0000000000000000000000000000000000000000000000000000000000000008080000000000000000000000000000000000000000000000000000000000000440000000000000000000000000d500b1d8e8ef31e21c99d1db9a6444d3adf1270000000000000000000000000000000500000000000000000000000000000005000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000800000000000000000000000000000000000000000000000000000000000000064d1660f990000000000000000000000000d500b1d8e8ef31e21c99d1db9a6444d3adf127000000000000000000000000055ff76bffc3cdd9d5fdbbc2ece4528ecce45047e00000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000800000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000000a4c9f12e9d00000000000000000000000055ff76bffc3cdd9d5fdbbc2ece4528ecce45047e0000000000000000000000000d500b1d8e8ef31e21c99d1db9a6444d3adf1270000000000000000000000000c2132d05d31c914a87c6611c10748aeb04b58e8f0000000000000000000000030f85a912448279111694f4ba4f85dc641c54b594000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000001a4b3af37c000000000000000000000000000000000000000000000000000000000000000808000000000000000000000000000000000000000000000000000000000000044000000000000000000000000c2132d05d31c914a87c6611c10748aeb04b58e8f000000000000000000000000000000010000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000800000000000000000000000000000000000000000000000000000000000000064d1660f99000000000000000000000000c2132d05d31c914a87c6611c10748aeb04b58e8f000000000000000000000000150f50e0d321f4607d589f939a28c5f10b13d7b900000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
"type": "MATIC_TRANSACTION"
}
{
"success": true,
"result": {
"transactionHash": "0x8c953e09d8cede9f4eb0d1ee96de4f5a99e31dba7e64312bb252a465de12d10d"
}
}
This needs to be done for each transaction that was returned from Step 3) Build Swap Transactions in the same order.