EVM Swaps

KyberSwap Aggregator EVM APIs

Download OpenAPI specification:

50KB

KyberSwapAggregator_EVMAPIs_v2.8.1.yaml

Note on integrations: clientID

In order to continuously improve the KyberSwap Aggregator, our APIs implement a client identifier field that enables us to understand how the APIs are being utilized. As a developer integrating with our APIs, please use the same clientID (i.e. company name) for:

• [V1] Get Swap Route

  • Header: x-client-id

  • Parameters: source

• [V1] Post Swap Route For Encoded Data

  • Header: x-client-id

  • Body: source

This will enable us to serve you better as we continuously strive to improve our Aggregator API. For integrators who have previously integrated with our Legacy API, we highly encourage migrating to the Latest APIs to ensure access to the latest features as well as improved service quality and efficiency.

Example

• [V1]GET

  • Header

    • x-client-id="yourCompanyNameHere"

  • Parameter

    • source="yourCompanyNameHere"

• [V1] POST

  • Header

    • x-client-id="yourCompanyNameHere"

  • Body

    • source="yourCompanyNameHere"

EVM swap APIs

If you're just getting started with the KyberSwap Aggregator, you can refer to our Execute A Swap With The Aggregator API dev guide for information and code samples on how to query and execute swaps at superior rates. Note that there is also a KyberSwap Widget option for integrators who require a simple minimal-code implementation. For existing integrators, please refer to Upgrading To APIv1 for further details on the motivation behind the upgrade as well as the relevant changes to swap flow and parameters.

To support more performant queries, KyberSwap highly encourages all integrators to implement the latest API [V1] version. While both versions of the API remains backwards compatible, only the [V1] APIs will continue to receive updates and hence developers are highly encouraged to implement the latest [V1] APIs to avoid any disruptions as the non-versioned API will eventually be deprecated.

API statuses and support

KyberSwap APIs uses the following statuses to minimize version miscommunications and ensure an uninterrupted service for the end user:

• Latest: API is functional and supported. This is the recommended version for all integrators (new and existing).

• Legacy: API remains functional with support for bugs only. No new feature updates.

• Deprecated: API is no longer functional and is not supported.

For all developers, it is highly recommended that you refer to the API with the Latest tag to ensure access to the latest features as well as improved service quality and efficiency. APIs which are planned to be sunset will be tagged Legacy during the transition period and thereafter moved to Deprecated.

The KyberSwap Docs will continue to maintain information regarding Legacy and Deprecated APIs.

Chain identifiers

The Aggregator APIs require a chain name to be included in the path when calling the APIs:

• Ethereum (ChainID: 1) -> ethereum

• BSC (ChainID: 56) -> bsc

• Arbitrum (ChainID: 42161) -> arbitrum

• Polygon PoS (ChainID: 137) -> polygon

• Optimism (ChainID: 10) -> optimism

• Avalanche (ChainID: 43114) -> avalanche

• Base (ChainID: 8453) -> base

• Cronos (ChainID: 25) -> cronos

• zkSync Era (ChainID: 324) -> zksync

• Fantom (ChainID: 250) -> fantom

• Linea (ChainID: 59144) -> linea

• Polygon zkEVM (ChainID: 1101) -> polygon-zkevm

• Aurora (ChainID: 1313161554) -> aurora

• BitTorrent Chain (ChainID: 199) -> bittorrent

• Scroll (ChainID: 534352) -> scroll

Latest

[V1] Get Swap Route

Retrieve the route information about a Swap between 2 tokens. Please use V1 GET API for a more performant route query. The route returned can then be combined with transaction specific params in the POST API payload to get the encoded data for submission to the KyberSwap router contract. Refer to Supported Exchanges And Networks for full list of supported networks.

GEThttps://aggregator-api.kyberswap.com/{chain}/api/v1/routes

Path parameters

chain*string

Full list of supported chains available on Docs.

Query parameters

Header parameters

Response

200422400: Bad Request (4001)400: Bad Request (4002)400: Bad Request (4005)400: Bad Request (4007)400: Bad Request (4008)400: Bad Request (4009)400: Bad Request (4010)400: Bad Request (4011)

Swap Found

Body

application/json

codestring

Response code

messagestring

Response message

dataobject

Response data

Request

JavaScriptCurl

const response = await fetch('https://aggregator-api.kyberswap.com/{chain}/api/v1/routes', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "code": "text",
  "message": "text",
  "data": {
    "routeSummary": {
      "tokenIn": "text",
      "amountIn": "text",
      "amountInUsd": "text",
      "tokenInMarketPriceAvailable": false,
      "tokenOut": "text",
      "amountOut": "text",
      "amountOutUsd": "text",
      "tokenOutMarketPriceAvailable": false,
      "gas": "text",
      "gasPrice": "text",
      "gasUsd": "text",
      "extraFee": {
        "feeAmount": "text",
        "chargeFeeBy": "currency_in",
        "isInBps": false,
        "feeReceiver": "text"
      },
      "route": [
        [
          {
            "pool": "text",
            "tokenIn": "text",
            "tokenOut": "text",
            "limitReturnAmount": "text",
            "swapAmount": "text",
            "amountOut": "text",
            "exchange": "text",
            "poolType": "text",
            "poolExtra": "text",
            "extra": "text"
          }
        ]
      ]
    },
    "routerAddress": "text"
  }
}

[V1] Post Swap Route For Encoded Data

Get the encoded swap route to be forwarded to the KyberSwap router contract. For simplicity, the request body should contain the routeSummary returned by [V1] Get Swap Route appended with the additional tx parameters. Please refer to Supported Exchanges And Networks for full list of supported networks.

POSThttps://aggregator-api.kyberswap.com/{chain}/api/v1/route/build

Path parameters

chain*string

Full list of supported chains available on Docs.

Header parameters

Body

application/json

routeSummary*object

The summarised routing data

deadlineinteger

Deadline (in Unix time second) for the transaction to be executed. Default will be +20 minute. Cannot be in the past.

slippageToleranceinteger

This is the amount of slippage the user can accept for his trade. The unit is bip. The value is in ranges [0, 2000], 10 means 0.1%. If no value is provided, slippageTolerance will be set to 0.

sender*string

Address which the swap input tokens will be debited from

recipient*string

Address which the swap output tokens will be sent to

sourcestring

ClientID of the party calling the API. Please use the same ClientID as the x-client-id in the header.

Response

200422400: Bad Request (4001)400: Bad Request (4002)400: Bad Request (4005)400: Bad Request (4007)400: Bad Request (4008)400: Bad Request (4009)400: Bad Request (4010)400: Bad Request (4011)

Successfully encoded

Body

application/json

codestring

Response code

messagestring

Response message

dataobject

Response data for encoded swap

Request

JavaScriptCurl

const response = await fetch('https://aggregator-api.kyberswap.com/{chain}/api/v1/route/build', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "routeSummary": {
        "tokenIn": "text",
        "amountIn": "text",
        "amountInUsd": "text",
        "tokenOut": "text",
        "amountOut": "text",
        "amountOutUsd": "text",
        "gas": "text",
        "gasPrice": "text",
        "gasUsd": "text",
        "extraFee": {
          "feeAmount": "text",
          "chargeFeeBy": "currency_in",
          "isInBps": false,
          "feeReceiver": "text"
        },
        "route": [
          [
            {
              "pool": "text",
              "tokenIn": "text",
              "tokenOut": "text",
              "limitReturnAmount": "text",
              "swapAmount": "text",
              "amountOut": "text",
              "exchange": "text",
              "poolType": "text",
              "poolExtra": "text",
              "extra": "text"
            }
          ]
        ]
      },
      "sender": "text",
      "recipient": "text"
    }),
});
const data = await response.json();

Response

{
  "code": "text",
  "message": "text",
  "data": {
    "amountIn": "text",
    "amountInUsd": "text",
    "amountOut": "text",
    "amountOutUsd": "text",
    "gas": "text",
    "gasUsd": "text",
    "outputChange": {
      "amount": "text",
      "percent": 0,
      "level": 0
    },
    "data": "text",
    "routerAddress": "text"
  }
}

Legacy

Get Swap Info with Encoded Data

Retrieve the information about a Swap between 2 tokens with encoded data to submit to KyberSwap router contract. Please refer to Supported Exchanges And Networks for full list of supported networks.

GEThttps://aggregator-api.kyberswap.com/{chain}/route/encode

Path parameters

chain*string

Full list of supported chains available on Docs.

Query parameters

Header parameters

Response

200

Swap Found

Body

application/json

inputAmountstring

The input amount of tokenIn, in wei

outputAmountstring

The input amount of tokenOut, in wei

totalGasinteger

Estimated gas fee

gasPriceGweistring

Current gas price in Gwei

gasUsdnumber

Current gas price in USD

amountInUsdnumber

Estimate of input value, in USD

amountOutUsdnumber

Estimate of out value, in USD

receivedUsdnumber

Estimate of final received value, in USD

swapsarray of array of SwapSequence (object)

Swap path, a 2-dimen array describe how swap is executed

encodedSwapDatastring

The encoded data to be sent to our router address

routerAddressstring

The KyberSwap router address

Request

JavaScriptCurl

const response = await fetch('https://aggregator-api.kyberswap.com/{chain}/route/encode', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "inputAmount": "text",
  "outputAmount": "text",
  "gasPriceGwei": "text",
  "gasUsd": 0,
  "amountInUsd": 0,
  "amountOutUsd": 0,
  "receivedUsd": 0,
  "swaps": [
    [
      {
        "pool": "text",
        "tokenIn": "text",
        "tokenOut": "text",
        "swapAmount": "text",
        "amountOut": "text",
        "limitReturnAmount": "text",
        "maxPrice": "text",
        "exchange": "text",
        "poolType": "text"
      }
    ]
  ],
  "encodedSwapData": "text",
  "routerAddress": "text"
}