---
updatedAt: 2025-11-05T21:50:04.000Z
agentTools:
  projectIndex: https://docs.venly.io/llms.txt
---

# 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

<Image alt="Token swap flow" align="center" border={true} src="https://files.readme.io/cb71a18-image.png">
  Token swap flow
</Image>

> 📘
>
> 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](https://venly.readme.io/reference/gettradingpairs)

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

<table><thead><tr><th width="208">Parameter</th><th width="340">Description</th></tr></thead><tbody><tr><td><code>from</code></td><td>This object holds details about the source token you desire to <strong>swap for</strong> another, including it's <strong>blockchain</strong>, <strong>symbol</strong>, and <strong>token address</strong>.</td></tr><tr><td><code>to</code></td><td>This object holds details about the destination token you desire to <strong>swap to</strong>, including it's <strong>blockchain</strong>, <strong>symbol</strong>, and <strong>token address</strong>.</td></tr><tr><td><code>secretType</code></td><td>The blockchain on which the wallet exists, for example: <strong>MATIC</strong>.</td></tr><tr><td><code>symbol</code></td><td>The symbol name of the token.</td></tr><tr><td><code>tokenAddress</code></td><td>Token address is the location of the smart contract responsible for managing the balances of all token holders.</td></tr></tbody></table>

> 📘
>
> 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](https://venly.readme.io/reference/getexchangerate)

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

<table><thead><tr><th width="195">Parameter</th><th width="94">Type</th><th width="102">Required</th><th width="340">Description</th></tr></thead><tbody><tr><td><code>fromSecretType</code></td><td>string</td><td>    ✅</td><td>The blockchain of source token.</td></tr><tr><td><code>toSecretType</code></td><td>object</td><td>    ✅</td><td>The blockchain of destination token.</td></tr><tr><td><code>fromToken</code></td><td>string</td><td>    ✅</td><td>The token address of the source token. (<em>you can get this from response body of the previous step</em>)</td></tr><tr><td><code>toToken</code></td><td>string</td><td>    ✅</td><td>The token address of the destination token. (<em>you can get this from response body of the previous step</em>)</td></tr><tr><td><code>amount</code></td><td>integer</td><td>    ✅</td><td>The amount of coins you want to swap.</td></tr><tr><td><code>orderType</code></td><td>string</td><td>    ✅</td><td>The type of order, which is <code>SELL</code>.</td></tr></tbody></table>

### 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:**

<table><thead><tr><th width="203">Parameter</th><th width="340">Description</th></tr></thead><tbody><tr><td><code>exchange</code></td><td>The name of the crypto exchanger.</td></tr><tr><td><code>orderType</code></td><td>The type of order, for this case, it is <code>SELL</code>.</td></tr><tr><td><code>inputAmount</code></td><td>The amount of source tokens you want to exchange.</td></tr><tr><td><code>outputAmount</code></td><td>The expected amount of destination tokens that you will receive after the swap.</td></tr><tr><td><code>slippage</code></td><td>The slippage percentage shows  the difference between the expected <code>outputAmount</code> and the actual <code>outputAmount</code>.</td></tr><tr><td><code>fee</code></td><td>This is the gas fee for the specific swap.</td></tr></tbody></table>

> 📘
>
> 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**](https://venly.readme.io/docs/swap-token-pairs-1#2-retrieve-exchange-rate).

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](https://venly.readme.io/reference/createswap)

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

<table><thead><tr><th width="195">Parameter</th><th width="94">Type</th><th width="102">Required</th><th width="340">Description</th></tr></thead><tbody><tr><td><code>walletId</code></td><td>string</td><td>    ✅</td><td>ID of the source wallet. (<em>Wallet that holds tokens to swap</em>)</td></tr><tr><td><code>destinationWalletId</code></td><td>string</td><td>    ✅</td><td>ID of the destination wallet. (<em>Wallet that will receive the destination tokens</em>)</td></tr><tr><td><code>fromSecretType</code></td><td>string</td><td>    ✅</td><td>The blockchain of source token.</td></tr><tr><td><code>toSecretType</code></td><td>string</td><td>    ✅</td><td>The blockchain of destination token.</td></tr><tr><td><code>fromToken</code></td><td>string</td><td>    ✅</td><td>The token address of the source token. (<em>you can get this from response body of the previous step</em>)</td></tr><tr><td><code>toToken</code></td><td>string</td><td>    ✅</td><td>The token address of the destination token. (<em>you can get this from response body of the previous step</em>)</td></tr><tr><td><code>inputAmount</code></td><td>integer</td><td>    ✅</td><td>The amount of source tokens you want to exchange.</td></tr><tr><td><code>outputAmount</code></td><td>integer</td><td>    ✅</td><td>The expected amount of destination tokens that you will receive after the swap.</td></tr><tr><td><code>orderType</code></td><td>string</td><td>    ✅</td><td>The type of order, for this case, it is <code>SELL</code>.</td></tr><tr><td><code>exchange</code></td><td>string</td><td>    ✅</td><td>The name of the crypto exchanger.</td></tr><tr><td><code>enableGasEstimate</code></td><td>boolean</td><td>    ✅</td><td>Indicate to include gas estimate (<em>response will contain value for the "<strong>gas</strong>" field</em>).</td></tr></tbody></table>

### 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](https://venly.readme.io/docs/swap-token-pairs-1#response-body-2) 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](https://venly.readme.io/reference/executetransaction_1)

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

<Table align={[null,"left",null,null,"left"]}>
  <thead>
    <tr>
      <th>
        Parameter
      </th>

      <th>
        Param Type
      </th>

      <th>
        Value
      </th>

      <th>
        Description
      </th>

      <th>
        Example Value
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `Signing-Method`
      </td>

      <td>
        Header
      </td>

      <td>
        `id:value`
      </td>

      <td>
        `id`: This is the ID of the signing method\
        `value`: This is the value of the signing method
      </td>

      <td>
        `756ae7a7-3713-43ee-9936-0dff50306488:123456`
      </td>
    </tr>
  </tbody>
</Table>

```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](https://venly.readme.io/docs/swap-token-pairs-1#3-build-swap-transaction)**, in the same order.