SWAP Token Pairs

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

4 Step Process to SWAP

SWAP Flow

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.

Call the following endpoint to get SWAP pairs:

Request Endpoint: reference

GET /api/wallets/{id}/swaps/pais

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

ParameterDescription
fromThis object holds details about the source token you desire to swap for another, including it's blockchain, symbol, and token address.
toThis object holds details about the destination token you desire to swap to, including it's blockchain, symbol, and token address.
secretTypeThe blockchain on which the wallet exists, for example: MATIC.
symbolThe symbol name of the token.
tokenAddressToken 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:

ParameterTypeRequiredDescription
fromSecretTypestring โœ…The blockchain of source token.
toSecretTypeobject โœ…The blockchain of destination token.
fromTokenstring โœ…The token address of the source token. (you can get this from response body of the previous step)
toTokenstring โœ…The token address of the destination token. (you can get this from response body of the previous step)
amountinteger โœ…The amount of coins you want to swap.
orderTypestring โœ…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:

ParameterDescription
exchangeThe name of the crypto exchanger.
orderTypeThe type of order, for this case, it is SELL.
inputAmountThe amount of source tokens you want to exchange.
outputAmountThe expected amount of destination tokens that you will receive after the swap.
slippageThe slippage percentage shows the difference between the expected outputAmount and the actual outputAmount.
feeThis 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:

ParameterTypeRequiredDescription
walletIdstring โœ…ID of the source wallet. (Wallet that holds tokens to swap)
destinationWalletIdstring โœ…ID of the destination wallet. (Wallet that will receive the destination tokens)
fromSecretTypestring โœ…The blockchain of source token.
toSecretTypestring โœ…The blockchain of destination token.
fromTokenstring โœ…The token address of the source token. (you can get this from response body of the previous step)
toTokenstring โœ…The token address of the destination token. (you can get this from response body of the previous step)
inputAmountinteger โœ…The amount of source tokens you want to exchange.
outputAmountinteger โœ…The expected amount of destination tokens that you will receive after the swap.
orderTypestring โœ…The type of order, for this case, it is SELL.
exchangestring โœ…The name of the crypto exchanger.
enableGasEstimateboolean โœ…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-Method parameter is to be passed as detailed below in the example request.

Example Request:

POST /api/transactions/execute
ParameterParam TypeValueDescription
Signing-MethodHeaderid:valueid: This is the ID of the signing method
value: This is the value of the signing method
{
    "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.