SWAP Token Pairs
This guide will explain how to SWAP tokens using the Wallet-API.
Due to the complexity of on chains swap performed across multiple decentralized exchanges the SWAP features are currently only supported on MAINNET (Production)
Different steps to perform a Token Swap
Token swap flow
Currently, the SWAP endpoints support the following chains:
- Ethereum
- Polygon (Matic)
- Avalanche
- Arbitrum
- Vechain
- BSC (Binance Smart Chain)
1. Retrieve Token Pairs
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:
Request Endpoint: reference
GET /api/wallets/{id}/swaps/pairs
Path Parameter:
{id} : This is the walletId. The SWAP pairs will be displayed based on the blockchain of this wallet.
Example Request:
GET /api/wallets/b97e9e8b-035c-40a0-bac0-96b07fc0444a/swaps/pairs
The wallet in this example is created on the Polygon (MATIC) blockchain.
Response Body:
{
"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"
}
}
]
}
Response Parameters under result array
result array| 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.
2. Retrieve Exchange Rate
Now you should have information about your desired swap pair. The next step is to calculate the exchange rate of the pair.
Request Endpoint: reference
GET /api/swaps/rates
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.
Query Parameters:
| 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. |
Example Request:
GET /api/swaps/rates?fromSecretType=MATIC&toSecretType=MATIC&fromToken=0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee&toToken=0x348e62131fce2f4e0d5ead3fe1719bc039b380a9&amount=1&orderType=SELL
Response Body:
{
"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 | This is the gas fee for the specific swap. |
Save the details of the
bestRate, as they will be used later in the guide.
3. Build Swap Transaction
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.
Request Endpoint: reference
POST /api/wallets/{id}/swaps
Path Parameter:
{id} : This is the ID of the source wallet. (Wallet that holds tokens to swap)
Request Body:
| 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). |
Example Request:
POST /api/wallets/b97e9e8b-035c-40a0-bac0-96b07fc0444a/swaps
{
"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
}
Response Body:
{
"success": true,
"result": [
{
"walletId": "b97e9e8b-035c-40a0-bac0-96b07fc0444a",
"gasPrice": 20000000000,
"gas": 523381,
"nonce": null,
"value": 1000000000000000000,
"to": "0x11111112542d85b3ef69ae05771c2dccff4faa26",
"network": null,
"data": "0x7c0252000000000000000000000000000f85a912448279111694f4ba4f85dc641c54b59400000000000000000000000000000000000000000000000000000000000000600000000000000000000000000000000000000000000000000000000000000180000000000000000000000000eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee000000000000000000000000c2132d05d31c914a87c6611c10748aeb04b58e8f0000000000000000000000000f85a912448279111694f4ba4f85dc641c54b594000000000000000000000000150f50e0d321f4607d589f939a28c5f10b13d7b90000000000000000000000000000000000000000000000000de0b6b3a764000000000000000000000000000000000000000000000000000000000000001d66ab00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000008e00000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000000500000000000000000000000000000000000000000000000000000000000000a000000000000000000000000000000000000000000000000000000000000001c0000000000000000000000000000000000000000000000000000000000000028000000000000000000000000000000000000000000000000000000000000004e0000000000000000000000000000000000000000000000000000000000000064000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000800000000000000000000000000000000000000000000000000000000000000064d1660f99000000000000000000000000eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee0000000000000000000000001fb53eb183b86582176f6aa8f4db72b62caf0d4b000000000000000000000000000000000000000000000000006a94d74f430000000000000000000000000000000000000000000000000000000000000000000000000000000000000d500b1d8e8ef31e21c99d1db9a6444d3adf127000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000d7621dc5821000000000000000000000000000000000000000000000000000000000000000000800000000000000000000000000000000000000000000000000000000000000004d0e30db000000000000000000000000000000000000000000000000000000000800000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000001a4b3af37c0000000000000000000000000000000000000000000000000000000000000008080000000000000000000000000000000000000000000000000000000000000440000000000000000000000000d500b1d8e8ef31e21c99d1db9a6444d3adf1270000000000000000000000000000000500000000000000000000000000000005000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000800000000000000000000000000000000000000000000000000000000000000064d1660f990000000000000000000000000d500b1d8e8ef31e21c99d1db9a6444d3adf127000000000000000000000000055ff76bffc3cdd9d5fdbbc2ece4528ecce45047e00000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000800000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000000a4c9f12e9d00000000000000000000000055ff76bffc3cdd9d5fdbbc2ece4528ecce45047e0000000000000000000000000d500b1d8e8ef31e21c99d1db9a6444d3adf1270000000000000000000000000c2132d05d31c914a87c6611c10748aeb04b58e8f0000000000000000000000030f85a912448279111694f4ba4f85dc641c54b594000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000001a4b3af37c000000000000000000000000000000000000000000000000000000000000000808000000000000000000000000000000000000000000000000000000000000044000000000000000000000000c2132d05d31c914a87c6611c10748aeb04b58e8f000000000000000000000000000000010000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000800000000000000000000000000000000000000000000000000000000000000064d1660f99000000000000000000000000c2132d05d31c914a87c6611c10748aeb04b58e8f000000000000000000000000150f50e0d321f4607d589f939a28c5f10b13d7b900000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
"type": "MATIC_TRANSACTION"
}
]
}
4. Execute SWAP
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 needs to be executed one by one 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.
Execute Transactions
The final step is executing the transactions. 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 run it on the following endpoint.
Request Endpoint: reference
POST /api/transactions/execute
In the header request, the
Signing-Methodparameter is to be passed as detailed below in the example request.
Example Request:
POST /api/transactions/execute
| Parameter | Param Type | Value | Description | Example Value |
|---|---|---|---|---|
Signing-Method | Header | id:value | id: This is the ID of the signing methodvalue: This is the value of the signing method | 756ae7a7-3713-43ee-9936-0dff50306488:123456 |
{
"walletId": "b97e9e8b-035c-40a0-bac0-96b07fc0444a",
"gasPrice": 20000000000,
"gas": 523381,
"nonce": null,
"value": 1000000000000000000,
"to": "0x11111112542d85b3ef69ae05771c2dccff4faa26",
"network": null,
"data": "0x7c0252000000000000000000000000000f85a912448279111694f4ba4f85dc641c54b59400000000000000000000000000000000000000000000000000000000000000600000000000000000000000000000000000000000000000000000000000000180000000000000000000000000eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee000000000000000000000000c2132d05d31c914a87c6611c10748aeb04b58e8f0000000000000000000000000f85a912448279111694f4ba4f85dc641c54b594000000000000000000000000150f50e0d321f4607d589f939a28c5f10b13d7b90000000000000000000000000000000000000000000000000de0b6b3a764000000000000000000000000000000000000000000000000000000000000001d66ab00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000008e00000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000000500000000000000000000000000000000000000000000000000000000000000a000000000000000000000000000000000000000000000000000000000000001c0000000000000000000000000000000000000000000000000000000000000028000000000000000000000000000000000000000000000000000000000000004e0000000000000000000000000000000000000000000000000000000000000064000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000800000000000000000000000000000000000000000000000000000000000000064d1660f99000000000000000000000000eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee0000000000000000000000001fb53eb183b86582176f6aa8f4db72b62caf0d4b000000000000000000000000000000000000000000000000006a94d74f430000000000000000000000000000000000000000000000000000000000000000000000000000000000000d500b1d8e8ef31e21c99d1db9a6444d3adf127000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000d7621dc5821000000000000000000000000000000000000000000000000000000000000000000800000000000000000000000000000000000000000000000000000000000000004d0e30db000000000000000000000000000000000000000000000000000000000800000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000001a4b3af37c0000000000000000000000000000000000000000000000000000000000000008080000000000000000000000000000000000000000000000000000000000000440000000000000000000000000d500b1d8e8ef31e21c99d1db9a6444d3adf1270000000000000000000000000000000500000000000000000000000000000005000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000800000000000000000000000000000000000000000000000000000000000000064d1660f990000000000000000000000000d500b1d8e8ef31e21c99d1db9a6444d3adf127000000000000000000000000055ff76bffc3cdd9d5fdbbc2ece4528ecce45047e00000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000800000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000000a4c9f12e9d00000000000000000000000055ff76bffc3cdd9d5fdbbc2ece4528ecce45047e0000000000000000000000000d500b1d8e8ef31e21c99d1db9a6444d3adf1270000000000000000000000000c2132d05d31c914a87c6611c10748aeb04b58e8f0000000000000000000000030f85a912448279111694f4ba4f85dc641c54b594000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000001a4b3af37c000000000000000000000000000000000000000000000000000000000000000808000000000000000000000000000000000000000000000000000000000000044000000000000000000000000c2132d05d31c914a87c6611c10748aeb04b58e8f000000000000000000000000000000010000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000800000000000000000000000000000000000000000000000000000000000000064d1660f99000000000000000000000000c2132d05d31c914a87c6611c10748aeb04b58e8f000000000000000000000000150f50e0d321f4607d589f939a28c5f10b13d7b900000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
"type": "MATIC_TRANSACTION"
}
Response Body:
{
"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.
Updated about 1 month ago