EVM Swaps

KyberSwap Aggregator EVM APIs

Download OpenAPI specification:

46KB

KyberSwapAggregator_EVMAPIs_v2.9.1.yaml

Note on integration: 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. A stricter rate limit will be applied if a clientId is not provided. As a developer integrating with our APIs, please preferably use the same clientID (i.e. company name or your app name) for:

• [V1] Get Swap Route

  • Header: x-client-id

• [V1] Post Swap Route For Encoded Data

  • Header: x-client-id

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 /routes

  • Header

    • x-client-id: MyAwesomeApp

• [V1] POST /route/build

  • Header

    • x-client-id: MyAwesomeApp

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 and the use of RFQ liquidity sources, 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 can make use of RFQ liquidity sources, 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

• zkSync Era (ChainID: 324) -> zksync

• Fantom (ChainID: 250) -> fantom

• Linea (ChainID: 59144) -> linea

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

• Scroll (ChainID: 534352) -> scroll

• Mantle (ChainID: 5000) -> mantle

• Blast (ChainID: 81457) -> blast

• Sonic (ChainID: 146) -> sonic

Latest

[V1] Get Swap Route

Find the best route to swap from tokenIn to tokenOut, supporting all liquidity sources including RFQ. Use this API to get a route preview before confirming the swap. 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 the full list of supported networks.

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

Path parameters

chain*string

Chain name. Full list of supported chains available on Docs.

Example: "ethereum"

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

codeinteger

Response code

messagestring

Response message

dataobject

Response data

Request

JavaScriptCurlPython

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

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)

{
  "code": 0,
  "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",
            "poolLength": 0,
            "poolType": "text"
          }
        ]
      ]
    },
    "routerAddress": "text"
  }
}

[V1] Post Swap Route For Encoded Data

Get the swap's calldata to be sent to the KyberSwap router contract. The request body must contain the routeSummary as exactly returned by [V1] Get Swap Route along with the additional tx related parameters. Please refer to Supported Exchanges And Networks for the full list of supported networks.

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

Path parameters

chain*string

Chain name. Full list of supported chains available on Docs.

Example: "ethereum"

Header parameters

Body

application/json

routeSummary*object

The summarised routing data as per returned from [V1] Get Swap Route

sender*string

Address from which the swap input tokens will be transferred from

recipient*string

Address to which the swap output tokens will be sent to

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 bps. The value is in ranges [0, 2000], 10 means 0.1%. If no value is provided, slippageTolerance will be set to 0.

referralstring

Referral info to include in the swap transaction's ClientData event.

sourcestring

The source of the swap to be recorded on-chain. You should use (and it defaults to be) the same value as the x-client-id in the header, unless you want to track separate sources.

enableGasEstimationboolean

If true, call eth_gasEstimate to get gas estimation for the transaction. Also helps to detect any potential reverts.

permitstring

Permit signature for tokenIn to allow swapping without a separate approval transaction beforehand. The permit's spender should be the routerAddress returned in the Get Swap Route API response.

ignoreCappedSlippageboolean

If true, the slippage tolerance can be any value. Please use with caution.

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

codeinteger

Response code

messagestring

Response message

dataobject

Response data for encoded swap

Request

JavaScriptCurlPython

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",
              "poolLength": 0,
              "poolType": "text",
              "poolExtra": "text",
              "extra": "text"
            }
          ]
        ]
      },
      "sender": "text",
      "recipient": "text"
    }),
});
const data = await response.json();

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)

{
  "code": 0,
  "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. RFQ liquidity sources are not supported. Please refer to Supported Exchanges And Networks for the 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

JavaScriptCurlPython

const response = await fetch('https://aggregator-api.kyberswap.com/{chain}/route/encode?tokenIn=text&tokenOut=text&amountIn=text&to=text', {
    method: 'GET',
    headers: {
      "X-Client-Id": "Latest"
    },
});
const data = await response.json();

Response

200

{
  "inputAmount": "text",
  "outputAmount": "text",
  "totalGas": 0,
  "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",
        "poolLength": 0,
        "poolType": "text"
      }
    ]
  ],
  "encodedSwapData": "text",
  "routerAddress": "text"
}