API Migration to v3

Migrate your v2 implementation to our API v3 endpoints

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 - Price discovery only. Returns available routes with expected amounts, fees, and execution times. Quotes are cached for 5 minutes.

2. /v3/swap - 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. 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:

v3 Quote

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

v2 Quote

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 .

v3 Swap

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

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:

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