# /v3/quote  - Request a swap quote

**Method:** `POST`\
**URL:** `https://api.swapkit.dev/v3/quote`

The first step towards performing a swap is requesting a quote, which will compare the price offered by the different swap providers.

Quotes are cached for 5 minutes, and can be used to obtain swap transaction details.

***

### Request Schema

Here's a detailed description of the different parameters:

<table data-full-width="false"><thead><tr><th width="189.8828125">Parameter</th><th width="92">Type</th><th width="89">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>sellAsset</code></td><td><code>string</code></td><td>Yes</td><td>The asset being sold (e.g. <code>"ETH.ETH"</code>).</td></tr><tr><td><code>buyAsset</code></td><td><code>string</code></td><td>Yes</td><td>The asset being bought (e.g. <code>"BTC.BTC"</code>).</td></tr><tr><td><code>sellAmount</code></td><td><code>string</code></td><td>Yes</td><td>Amount in basic units (decimals separated with a dot).</td></tr><tr><td><code>sourceAddress</code></td><td><code>string</code></td><td>No</td><td>Blockchain address to send the asset from. Must be a valid address for the buy asset's chain<br><br>Note - This is optional. By providing here we can screen the address against our index of bad addresses. Full screen is done in the <code>/v3/swap</code> endpoint</td></tr><tr><td><code>destinationAddress</code></td><td><code>string</code></td><td>No</td><td>Recipient blockchain address to send the asset to. Must be a valid address for the buy asset's chain<br><br>Note - This is optional. By providing here we can screen the address against our index of bad addresses. Full screen is done in the <code>/v3/swap</code> endpoint</td></tr><tr><td><code>providers</code></td><td><code>array</code></td><td>No</td><td>Limits the possible liquidity providers. If omitted, all available providers are used.</td></tr><tr><td><code>slippage</code></td><td><code>number</code></td><td>No</td><td>Max slippage in percentage (5 = 5%).</td></tr><tr><td><code>affiliateFee</code></td><td>number</td><td>No</td><td>Affiliate fee override in basis points (0-1000, max 10%). Must be a positive integer. If it is not provided, the API key configured fee tiers are applied.</td></tr><tr><td><code>cfBoost</code></td><td><code>boolean</code></td><td>No</td><td>Enables Chainflip boost for better rates.</td></tr><tr><td><code>maxExecutionTime</code></td><td><code>number</code></td><td>No</td><td>Maximum execution time in seconds. Routes exceeding this time are filtered out.</td></tr></tbody></table>

**Note:** Asset names for `sellAsset` and `buyAsset` should follow the following nomenclature:

* Chain.Asset (e.g., `"BTC.BTC"` or `"ARB.ETH"`)
* Chain.Asset-ContractAddress (e.g., `"ETH.USDC-0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"`)

This is the `identifier` as provided in the [`/tokens`](/swapkit-api/tokens-request-supported-tokens-by-a-swap-provider.md) or [`/swapTo`](/swapkit-api/swapto-request-buy-swap-options.md) endpoints.

***

#### Example request

A simple request to trade `ETH.ETH`to `BTC.BTC`may omit the `providers` array if you can manage them in the response, but should include the amount and slippage settings.

The expiration time of a quote is of 60 seconds. After that, you may request a new one or it will be automatically requested if a swap is openned using this `routeId` .

{% hint style="info" %}
Using the header `x-api-key` in your `/quote` request automatically applies your affiliate addresses and fee values set up through our [partners dashboard](/monetization.md#step-3-set-affiliate-fee-tiers) in the response parameters.
{% endhint %}

{% tabs %}
{% tab title="cURL" %}

```sh
curl -X POST "https://api.swapkit.dev/v3/quote" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_VARIABLE_HERE" \
  -d '{
    "sellAsset": "ETH.USDC-0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "buyAsset": "BTC.BTC",
    "sellAmount": "300",
    "slippage": 2
  }'
```

{% endtab %}
{% endtabs %}

***

### Quote Response Schema

| Field            | Type                          | Description                                                                                                    |
| ---------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `quoteId`        | `string`                      | UUID for this quote response                                                                                   |
| `routes`         | `QuoteRoute[]`                | An array of routes with an individual `routeId` to request a swap with. `QuoteRoute` schema is explained below |
| `providerErrors` | `QuoteError[]` or `undefined` | Optional. If errors encountered from providers, details returned here. `QuoteError` schema is explained below  |
| `error`          | `string` or `undefined`       | In case of a bad request, root level `error` is provided.                                                      |

#### Quote Route Schema

Each route identifies a provider or group of providers for the swap. Each item in the routes array contains the information needed to compare between them:

<table><thead><tr><th width="265">Field</th><th width="84">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>routeId</code></td><td><code>string</code></td><td>UUID of this specific swap response.</td></tr><tr><td><code>providers</code></td><td><code>array</code></td><td>List of providers available for this route (<code>CHAINFLIP</code>, <code>THORHCAIN</code> etc.).</td></tr><tr><td><code>sellAsset</code></td><td><code>string</code></td><td>The asset being sold (e.g., <code>“ETH.ETH”</code>).</td></tr><tr><td><code>buyAsset</code></td><td><code>string</code></td><td>The asset being bought (e.g., <code>“BTC.BTC”</code>).</td></tr><tr><td><code>sellAmount</code></td><td><code>string</code></td><td>Amount of the sell asset in smallest units.</td></tr><tr><td><code>expectedBuyAmount</code></td><td><code>string</code></td><td>Estimated amount of the buy asset to be received.</td></tr><tr><td><code>expectedBuyAmountMaxSlippage</code></td><td><code>string</code></td><td>Worst-case buy amount considering max slippage.</td></tr><tr><td><code>fees</code></td><td><code>array</code></td><td>List of fees applied to the swap (inbound, network, affiliate, service).</td></tr><tr><td><code>estimatedTime</code></td><td><code>object</code></td><td>Estimated time for different phases of the swap.</td></tr><tr><td><code>totalSlippageBps</code></td><td><code>number</code></td><td>Expected total slippage.</td></tr><tr><td><code>legs</code></td><td><code>array</code></td><td>The different involved steps in the swap.</td></tr><tr><td><code>warnings</code></td><td><code>array</code></td><td>Potential warnings about this swap provider.</td></tr><tr><td><code>meta</code></td><td><code>object</code></td><td>Other information about the transaction and the assets involved.</td></tr><tr><td><code>meta.tags</code></td><td><code>array</code></td><td> <code>"FASTEST"</code>, <code>"RECOMMENDED"</code> or <code>"CHEAPEST"</code> tag help sort the routes available</td></tr><tr><td><code>nextActions</code></td><td><code>object</code></td><td>Data about next request to make in the flow.`{ method: string; url: string; payload: object</td></tr></tbody></table>

***

### Quote Error Schema

| Field       | Type     | Description                                   |
| ----------- | -------- | --------------------------------------------- |
| `provider`  | `string` | Specific ProviderName value                   |
| `errorCode` | `string` | One of the possible error codes listed below. |
| `message`   | `string` | Message relating to thrown error.             |

#### Quote Error Codes and messages

| Error                             | Message                                                     | Status Code | Scenario                                                              |
| --------------------------------- | ----------------------------------------------------------- | ----------- | --------------------------------------------------------------------- |
| `noRoutesFound`                   | No routes found for swap from {sellAsset} to {buyAsset}     | 404         | No valid swap path exists between the requested token pair.           |
| `blackListAsset`                  | Asset {asset} is blacklisted                                | 400         | The sell or buy asset is identified as a scam token in our blacklist. |
| `apiKeyInvalid` or `unauthorized` | "Invalid API key" / "Unauthorized”                          | 401         | Missing, expired, or invalid API key in x-api-key header.             |
| `invalidRequest`                  | "Request body is required and must be a valid JSON object”. | 400         | Request body is missing, null, or malformed JSON.                     |

The `invalidRequest` error may include additional details depending on the missing parameters. Make sure to check the JSON formatting in the request.

***

### Fees breakdown

Fees are categorized into different types based on their role in the swap process.

<table><thead><tr><th width="297">Fee Type</th><th>Description</th></tr></thead><tbody><tr><td><strong>Inbound</strong></td><td>Fee for transferring the sell asset, paid from the user's wallet.</td></tr><tr><td><strong>Network</strong></td><td>Blockchain transaction fee for processing the swap.</td></tr><tr><td><strong>Affiliate</strong></td><td>Fee paid to the specified affiliate.</td></tr><tr><td><strong>Service</strong></td><td>SwapKit's service fee.</td></tr><tr><td><strong>Outbound</strong></td><td>Fee for transferring the buy asset to the destination address.</td></tr><tr><td><strong>Liquidity</strong></td><td>Fee applied by the liquidity provider to facilitate the swap.</td></tr></tbody></table>

Only the inbound fee will be paid from the source wallet. The other fees are deducted from the output, and the output values provided by the endpoint already take this into consideration.

***

### Estimated time

The estimated time in seconds for the swap is divided into the following phases:

* **Inbound:** Time taken to receive the sell asset.
* **Swap:** Time taken for the swap process.
* **Outbound:** Time taken to transfer the bought asset to the destination. This includes the provider outbound time, not only the transaction time.
* **Total:** The sum of all time estimates.

#### **Example estimated time:**

```json
"estimatedTime": {
    "inbound": 30,
    "swap": 6,
    "outbound": 624,
    "total": 660
}
```

***

### Route metadata

The `meta` section provides additional information about the swap.

| **assets** | Details of the involved assets, including price and image links. |
| ---------- | ---------------------------------------------------------------- |
| **tags**   | \["FASTEST", "RECOMMENDED", "CHEAPEST"]                          |

#### **Example `meta` Object:**

```json
"meta": {
    "assets": [{
        "asset": "ETH.ETH",
        "price": 2752.14,
        "image": "https://storage.googleapis.com/token-list-swapkit/images/eth.eth.png"
    }, {
        "asset": "BTC.BTC",
        "price": 97648,
        "image": "https://storage.googleapis.com/token-list-swapkit/images/btc.btc.png"
    }],
    "tags": ["FASTEST"]
}
```

The `"tags"`can help recognize what SwapKit considers the best routes by filtering through the `["FASTEST", "RECOMMENDED", "CHEAPEST"]` identification.

<table><thead><tr><th width="283">Tag</th><th>Description</th></tr></thead><tbody><tr><td><strong>RECOMMENDED</strong></td><td>Best overall route based on output and speed.</td></tr><tr><td><strong>CHEAPEST</strong></td><td>The route with the maximum output.</td></tr><tr><td><strong>FASTEST</strong></td><td>The route with the shortest total estimated time.</td></tr></tbody></table>

To determine the `RECOMMENDED` route when multiple options are available, each route gets two normalized scores:

* **Output score (0-100)**: Compare the route's output to the maximum output of the available routes, multiplied by 100 for weight.\
  `(routeOutput / maxOutput) * 100`&#x20;
* **Time score (0-50)**: Compare the route's expected confirmation time to the minimum confirmation time of the available routes, substracting from 50 to give it  a dynamic weight. The fastest route will obtain 50 points here.\
  `50 - abs(routeTime - minTime) / (maxTime - minTime)`

The weights between output and time are dynamic, based on how much difference there is between the fastest route and the route being analyzed.&#x20;

<table><thead><tr><th width="283">Time spread (Current vs Fastest)</th><th>Output weight</th><th>Time weight</th></tr></thead><tbody><tr><td>≤ 60 seconds</td><td>100 %</td><td>0 %</td></tr><tr><td><strong>60s - 5 min</strong></td><td>95 %</td><td> 5 %</td></tr><tr><td><strong>5 - 15 min</strong></td><td>90 %</td><td>10 %</td></tr><tr><td><strong>> 15 min</strong></td><td>80 %</td><td>20 %</td></tr></tbody></table>

The weights are then multiplied to the score and the route with the highest total is tagged as `RECOMMENDED` . It is simply `outputScore * outputWeight + timeScore * timeWeight` .

***

### Next Actions

The `nextActions` object includes information about the request to use next. Generally it will point to the `/swap` endpoint which will return a transaction object, but the `/swap` endpoint may only approve spending for a token and include a new `nextActions` object.

As an example, it could be something like this, which includes the `method`, `url` and `payload` to use. The `"soureAddress"` and `"destinationAddress"` need to be filled in:

```json
"nextActions": [
    {
        "method": "POST",
        "url": "/swap",
        "payload": {
            "routeId": "14ddcf49-4adb-4817-a55e-1bfb1296283d"
        }
    }
]
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.swapkit.dev/swapkit-api/v3-quote-request-a-swap-quote.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.