Build Route (Auto)

Build optimal swap routes automatically using KyberSwap's aggregator

The Build Route endpoint is the primary API for obtaining optimal token swap routes. It queries KyberSwap's aggregator, filters results to supported DEX adapters, and returns ready-to-execute transaction data.

Endpoint

POST /api/v1/route/build

Request

Headers

Content-Type: application/json

Body Parameters

Parameter	Type	Required	Description
chain	string	✅	Chain identifier (bsc, ethereum)
tokenIn	string	✅	Input token contract address
tokenOut	string	✅	Output token contract address
amountIn	string	✅	Input amount in wei
sender	string	✅	Sender wallet address
recipient	string	✅	Recipient wallet address
slippageTolerance	integer	❌	Max slippage in basis points (default: 50)
deadline	integer	❌	Unix timestamp deadline (default: 20 min from now)
includedSources	array	❌	DEX sources to include (default: all supported)
gasPrice	string	❌	Custom gas price in wei

Request Example

{
  "chain": "bsc",
  "tokenIn": "0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c",
  "tokenOut": "0x55d398326f99059fF775485246999027B3197955",
  "amountIn": "1000000000000000000",
  "sender": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "recipient": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "slippageTolerance": 50,
  "deadline": 1735689600,
  "includedSources": [
    "uniswap",
    "uniswapv3",
    "pancake",
    "pancake-v3"
  ],
  "gasPrice": "5000000000"
}

Supported DEX Sources

Source	Description	Versions
uniswap	UniswapV2	V2
uniswapv3	UniswapV3	V3, V4
pancake	PancakeSwap	V2
pancake-v3	PancakeSwap	V3

Default Behavior

If includedSources is not specified, all supported DEX adapters will be considered for routing.

Response

Success Response (200 OK)

{
  "code": 0,
  "message": "success",
  "data": {
    "tokenIn": "0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c",
    "tokenOut": "0x55d398326f99059fF775485246999027B3197955",
    "amountIn": "1000000000000000000",
    "amountOut": "580123456789012345678",
    "minAmountOut": "577222222222222222222",
    "gas": "150000",
    "gasPrice": "5000000000",
    "gasUsd": 0.0234,
    "amountInUsd": 580.12,
    "amountOutUsd": 579.89,
    "aggregatorAddress": "0x27e33A8286d5Fd2956E24C2BcD62Fdd410c5bDf9",
    "executorAddress": "0x799F4A8586aa32EeA7CFd5a6cba85A8e0aDC4a5E",
    "executorData": "0x00bb4cdb9cbd36b01bd1cbaebf2de08d9173bc095c...",
    "value": "0",
    "swapType": "batch",
    "routeInfo": {
      "routes": [
        {
          "adapter": "PancakeSwapV3",
          "adapterAddress": "0x38BF57A209b9CAeCd3525B08B0CB1BCC7a598E4B",
          "percentage": 60,
          "path": {
            "tokens": [
              "0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c",
              "0x55d398326f99059fF775485246999027B3197955"
            ],
            "fees": [3000]
          }
        },
        {
          "adapter": "UniswapV2",
          "adapterAddress": "0x90e1C85D0542B8963906330825ddE2dec66b78C3",
          "percentage": 40,
          "path": {
            "tokens": [
              "0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c",
              "0x55d398326f99059fF775485246999027B3197955"
            ]
          }
        }
      ]
    }
  }
}

Response Fields

Field	Type	Description
tokenIn	string	Input token address
tokenOut	string	Output token address
amountIn	string	Input amount in wei
amountOut	string	Expected output amount in wei
minAmountOut	string	Minimum output after slippage
gas	string	Estimated gas units
gasPrice	string	Gas price in wei
gasUsd	number	Estimated gas cost in USD
amountInUsd	number	Input value in USD
amountOutUsd	number	Output value in USD
aggregatorAddress	string	DexAggregator contract address
executorAddress	string	Executor contract address
executorData	string	ABI-encoded calldata for execution
value	string	Native token value to send (for ETH/BNB swaps)
swapType	string	Type: simple, batch, multihop, or parallel_multihop
routeInfo	object	Detailed route breakdown

Swap Types

The API automatically detects the optimal swap type:

• simple: Single DEX, direct token swap

• batch: Multiple DEXes splitting liquidity

• multihop: Sequential swaps through intermediate tokens

• parallel_multihop: Complex parallel routing

See Swap Types for detailed explanations.

Error Responses

400 Bad Request

{
  "code": 1001,
  "message": "invalid chain: unsupported",
  "data": null
}

500 Internal Server Error

{
  "code": 1002,
  "message": "failed to fetch route from KyberSwap",
  "data": null
}

See Error Codes for complete list.

Usage Examples

cURL

curl -X POST http://localhost:8081/api/v1/route/build \
  -H "Content-Type: application/json" \
  -d '{
    "chain": "bsc",
    "tokenIn": "0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c",
    "tokenOut": "0x55d398326f99059fF775485246999027B3197955",
    "amountIn": "1000000000000000000",
    "sender": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "recipient": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "slippageTolerance": 50
  }'

JavaScript (fetch)

const response = await fetch('http://localhost:8081/api/v1/route/build', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    chain: 'bsc',
    tokenIn: '0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c',
    tokenOut: '0x55d398326f99059fF775485246999027B3197955',
    amountIn: '1000000000000000000',
    sender: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
    recipient: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
    slippageTolerance: 50,
  }),
});

const data = await response.json();

if (data.code === 0) {
  console.log('Optimal route found!');
  console.log('Expected output:', data.data.amountOut);
  console.log('Min output:', data.data.minAmountOut);
  console.log('Swap type:', data.data.swapType);
  console.log('Executor data:', data.data.executorData);
} else {
  console.error('Error:', data.message);
}

Python (requests)

import requests

response = requests.post(
    'http://localhost:8081/api/v1/route/build',
    json={
        'chain': 'bsc',
        'tokenIn': '0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c',
        'tokenOut': '0x55d398326f99059fF775485246999027B3197955',
        'amountIn': '1000000000000000000',
        'sender': '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
        'recipient': '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
        'slippageTolerance': 50
    }
)

data = response.json()

if data['code'] == 0:
    print(f"Expected output: {data['data']['amountOut']}")
    print(f"Min output: {data['data']['minAmountOut']}")
    print(f"Swap type: {data['data']['swapType']}")

Go

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

type BuildRouteRequest struct {
    Chain             string   `json:"chain"`
    TokenIn           string   `json:"tokenIn"`
    TokenOut          string   `json:"tokenOut"`
    AmountIn          string   `json:"amountIn"`
    Sender            string   `json:"sender"`
    Recipient         string   `json:"recipient"`
    SlippageTolerance int      `json:"slippageTolerance"`
}

type BuildRouteResponse struct {
    Code    int    `json:"code"`
    Message string `json:"message"`
    Data    struct {
        AmountOut    string `json:"amountOut"`
        MinAmountOut string `json:"minAmountOut"`
        ExecutorData string `json:"executorData"`
        SwapType     string `json:"swapType"`
    } `json:"data"`
}

func main() {
    req := BuildRouteRequest{
        Chain:             "bsc",
        TokenIn:           "0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c",
        TokenOut:          "0x55d398326f99059fF775485246999027B3197955",
        AmountIn:          "1000000000000000000",
        Sender:            "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
        Recipient:         "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
        SlippageTolerance: 50,
    }

    jsonData, _ := json.Marshal(req)

    resp, err := http.Post(
        "http://localhost:8081/api/v1/route/build",
        "application/json",
        bytes.NewBuffer(jsonData),
    )
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)

    var result BuildRouteResponse
    json.Unmarshal(body, &result)

    if result.Code == 0 {
        fmt.Printf("Expected output: %s\n", result.Data.AmountOut)
        fmt.Printf("Min output: %s\n", result.Data.MinAmountOut)
        fmt.Printf("Swap type: %s\n", result.Data.SwapType)
    } else {
        fmt.Printf("Error: %s\n", result.Message)
    }
}

Execution Flow

1. Request Route - Send swap parameters to /api/v1/route/build

2. Receive Data - Get executorData and contract addresses

3. Approve Token - Call approve() on input token (if not native)

4. Execute Swap - Call smartSwapByOrderId() on aggregator contract

5. Verify Output - Check received amount ≥ minAmountOut

See Integration Guide for complete implementation examples.

Best Practices

Recommendations

1. Always set deadline - Prevent stale transactions

2. Validate addresses - Check token and wallet addresses before sending

3. Handle errors gracefully - Implement retry logic for network failures

4. Check minAmountOut - Verify slippage protection before execution

5. Monitor gas prices - Adjust based on network conditions

Important Notes

• Routes are valid for ~30 seconds due to market volatility

• Always approve tokens before swapping (except native tokens)

• The executorData is ready-to-use ABI-encoded calldata

• Native token swaps (ETH/BNB) require sending value with transaction

Related Endpoints

• Custom Route - Build routes manually

• Get Contracts - Get contract addresses

• Get Chains - List supported chains

Need Help?

• 📖 See Swap Types to understand routing logic

• 💻 Check JavaScript Integration for full examples

• 🐛 Report issues on GitHub