SWAP Token Pairs

This guide will explain how to SWAP tokens using the Wallet-API.

4 Step Process to SWAP

SWAP Flow

Currently, the SWAP endpoints support the following chains:

• Ethereum

• Arbitrum

• Vechain

• Polygon (Matic)

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

Endpoint

Call the following endpoint to get SWAP pairs:

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

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.

Endpoint

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.

GET /api/swaps/rates

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

Endpoint

POST /api/wallets/{id}/swaps

Path Parameter

{id} : This is the ID of the source wallet. (Wallet that holds tokens to swap)

Request Body Parameters

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",
            "pincode": null,
            "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 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.

4.1) Prepare Transactions

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.

4.2) Execute Transactions

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.

Endpoint

POST /api/transactions/execute

Example Request

POST /api/transactions/execute

{
    "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"
}

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.