SWAP Token Pairs

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

📘

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

HTTP

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:

HTTP

GET /api/wallets/b97e9e8b-035c-40a0-bac0-96b07fc0444a/swaps/pairs

📘

The wallet in this example is created on the Polygon (MATIC) blockchain.

Response Body:

JSON

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

Request Endpoint: reference

HTTP

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:

HTTP

GET /api/swaps/rates?fromSecretType=MATIC&toSecretType=MATIC&fromToken=0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee&toToken=0x348e62131fce2f4e0d5ead3fe1719bc039b380a9&amount=1&orderType=SELL

Response Body:

JSON

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

HTTP

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:

HTTP

POST /api/wallets/b97e9e8b-035c-40a0-bac0-96b07fc0444a/swaps

JSON

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

JSON

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

HTTP

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:

HTTP

POST /api/transactions/execute
Parameter
Param Type
Value
Description
Example Value

Signing-Method

Header

id:value

id: This is the ID of the signing method value: This is the value of the signing method

756ae7a7-3713-43ee-9936-0dff50306488:123456

JSON

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

JSON

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

PreviousFilter NSFW NFTsNextGasless/Meta Transactions

Last updated