# API Migration to v3

### Overview

SwapKit v3 API presents a new flow that clearly separates responsibilities into 2 distinct services. This simplifies the integration and introduces a more deterministic\
developer experience, and as a result of reduced computation, latency has been lowered.

On top of that, SwapKit’s fees are reduced from 0.20% on swaps of all sizes to:

* 0.15% on swaps between $0 and $500k.
* 0.12% on swaps between $500k and $1m.
* 0.10% on swaps +$1m.
* 0.01% on stable <> stable swaps.

Previously, the `includeTx` request parameter would be used to signal building of transactions. This created an unclear separation of concerns and made it difficult for developers to create a clear flow which clearly separates retrieving quotes from the market, and building a transaction for a user's chosen route.

#### The New v3 Flow

v3 introduces a clear two-step process:

1. [`/v3/quote`](/swapkit-api/v3-quote-request-a-swap-quote.md) - Price discovery only. Returns available routes with expected amounts, fees, and execution times. Quotes are cached for 5 minutes.
2. [`/v3/swap`](/swapkit-api/v3-swap-obtain-swap-transaction-details.md) - Transaction execution. Takes a routeId from the quote and builds a ready-to-broadcast transaction.

This two-step process is also detailed in the [quote and swap implementation flow](/swapkit-api/quote-and-swap-implementation-flow.md). There are no changes to the other SwapKit endpoints.\
Migrating an existing v2 integration to v3 is a matter of separating the use of `"includeTx"` into calling two separate endpoints instead, and adapting to fetch the appropiate route identification `routeId` .

### Changes to the /quote endpoint

The v2 version of the `/quote` endpoint required passing the addresses involved to request a quote and setting the `"includeTx` flag on `true` or `false` to request swap data.

This is no longer necessary, we can compare two example payloads:

{% tabs %}
{% tab title="v3 Quote" %}

```json
{
  "sellAsset": "ETH.ETH",
  "buyAsset": "BTC.BTC",
  "sellAmount": "2",
  "slippage": 3
}
```

{% endtab %}

{% tab title="v2 Quote" %}

```json
{
  "sellAsset": "ETH.ETH",
  "buyAsset": "BTC.BTC",
  "sellAmount": "2",
  "sourceAddress": "0x0a4c79cE84202b03e95B7a692E5D728d83C44c76",
  "destinationAddress": "168w95Wf8tphgM7DPREXr8zLnVoE2wJCAN",
  "slippage": 3,
  "includeTx": false
}
```

{% endtab %}
{% endtabs %}

The data in the response is similar, except that you will not find transaction details here until you use `/v3/swap` to request them.\
Instead, each offered route is identified by a `routeId` string that can be used to request swap details and `"nextActions"` data in case the user needs to.

### The new /swap endpoint

The `/v3/swap/` or just `/swap` endpoint is called as a follow up to a chosen route from a `/v3/quote` response.\
The addresses are added in this step, and they will be checked for AML compliance.

The new `disableBuildTx` can be used in case you want to build the transaction yourself. Otherwise, we will provide a transaction ready to sign, similar to the v2 flow with `"includeTx": true` .

Without any optional parameters, it is just filling the missing information from a quote:

* Select a route
* Provide `sourceAddress` and `destinationAddress` .

{% tabs %}
{% tab title="v3 Swap" %}

```json
{
  "routeId": "5ea8cd3a-05ae-4737-b223-dbcd4c7a6493",
  "sourceAddress": "0x0a4c79cE84202b03e95B7a692E5D728d83C44c76",
  "destinationAddress": "168w95Wf8tphgM7DPREXr8zLnVoE2wJCAN"
}
```

{% endtab %}
{% endtabs %}

The response will include the transaction information to perform a swap. This informationmatches what v2 returned when `"includeTx": true` was included.\
As an example, for an EVM sell chain it could be something like this. In this case, this is a simple transfer without any contract being involved:

```json
"tx": {
        "to": "0x4e6960159d85254cb8e88483793f6fa8e9a49a4c",
        "from": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
        "gas": "0x5208",
        "gasPrice": "0x9129260",
        "value": "3000000000000000000",
        "data": "0x"
    },
```


---

# 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/spotlights/api-migration-to-v3.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.