GET /routeAndSwap

GET get best routes and generate swap transaction calldata to swap in Butter router

Request Parameters

Name	Location	Type	Required	Description
fromChainId	query	string	yes	source chain id, the supported chain ID list can be get from endpiont /supportedChainList
toChainId	query	string	yes	destination chain id
amount	query	string	yes	amount of source token
tokenInAddress	query	string	yes	address of source token, use 0x0000000000000000000000000000000000000000 for native token on most blockchains, T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb for native token on Tron
tokenOutAddress	query	string	yes	address of destination token
type	query	string	yes	swap type, one of "exactIn" and "exactOut"
slippage	query	string	yes	slippage of swap, a integer in range [0, 5000], e.g, 100 means 1%. For cross chain swap, the min slippage is 150， for cross chain from/to TON/BTC, min slippage is 300
from	query	string	yes	sender address on source chain
receiver	query	string	yes	receiver address on destination chain
entrance	query	string	yes	entrance of swap, please contact us for applying your dedicated entrance.
callData	query	string	no	encoded call data if receiver is a contract
caller	query	string	no	caller of butter router contract, e.g., the smart contract address who calls butter rotuer, or the user account who directly calls butter router
affiliate	query	string	no	affiliate nickname and fee rate, the format is '<nickname>[:rate]'. If fee rate is not provided, the default base rate (aka source rate) will be used, note that the rate could not be greater than max rate (aka target rate). E.g., for nickname 'butter' which has configured base rate to 0.1% and max rate to 1%, affiliate=butter means the affiliate charges 0.1% affiliate fee and affiliate=butter:50 means it charges 0.5% affiliate fee.

Request Example

GET /routeAndSwap?fromChainId=1&toChainId=56&amount=1&tokenInAddress=0x0000000000000000000000000000000000000000&tokenOutAddress=0x0000000000000000000000000000000000000000&type=exactIn&slippage=150&entrance=<entrance>&from=0x2D4C407BBe49438ED859fe965b140dcF1aaB71a9&receiver=0x2D4C407BBe49438ED859fe965b140dcF1aaB71a9

Responses Structure

The response contains the following fields:

Field	Type	Description
errno	number	Error code. 0 means success, other values indicate errors, see error code list.
message	string	Response message. If the request was successful it is success, otherwise it gives corresponding error message.
data	array	Contains data on the swap route path, fees, etc.

data Field

The data field contains an array with one or more route and swap data. Each item has the following fields:

Field	Type	Description
route	object	The detailed route information, please refer to route API for details.
txParam	object	The swap transaction information, please refer to swap API for details.

Response Examples

1. get best routes and swap transaction calldata successfully

200 Response

{
  "errno": 0,
  "message": "success",
  "data": [
    {
      "route": {
        "diff": "0",
        "bridgeFee": {
          "amount": "0.00338",
          "symbol": "WETH",
          "address": "0x05aB928d446d8ce6761e368c8e7bE03C3168A9ec",
          "chainId": 22776,
          "in": {
            "amount": "0.0",
            "token": {
              "address": "0x05aB928d446d8ce6761e368c8e7bE03C3168A9ec",
              "name": "Mapped Wrapped Ether",
              "decimals": 18,
              "symbol": "WETH",
              "icon": "https://s3.amazonaws.com/map-static-file/mapSwap/ethereum/0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2/logo.png"
            }
          },
          "out": {
            "amount": "0.00338",
            "token": {
              "address": "0x05aB928d446d8ce6761e368c8e7bE03C3168A9ec",
              "name": "Mapped Wrapped Ether",
              "decimals": 18,
              "symbol": "WETH",
              "icon": "https://s3.amazonaws.com/map-static-file/mapSwap/ethereum/0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2/logo.png"
            }
          },
          "affiliate": {
            "amount": "0.0",
            "token": {
              "address": "0x05aB928d446d8ce6761e368c8e7bE03C3168A9ec",
              "decimals": 18,
              "symbol": "ETH",
              "icon": "https://s3.amazonaws.com/map-static-file/mapSwap/ethereum/0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2/logo.png"
            },
            "list": [],
            "data": "0x00"
          }
        },
        "tradeType": 0,
        "gasFee": {
          "amount": "0.00067511265096",
          "symbol": "ETH",
          "inUSD": "2.355691630386166"
        },
        "swapFee": {
          "nativeFee": "0.0",
          "tokenFee": "0.0"
        },
        "feeConfig": {
          "feeType": 1,
          "referrer": "0x200AEe9ba7040d778922A763CE8A50948d61AFF5",
          "rateOrNativeFee": 0
        },
        "gasEstimated": "170000",
        "gasEstimatedTarget": "841800",
        "timeEstimated": 1080,
        "hash": "0x9e9a0b7e4c0e06b2242b49011cfd06665b3934397aba2d52b0f968f11933cac3",
        "entrance": "<entrance>",
        "timestamp": 1735105523772,
        "hasLiquidity": true,
        "srcChain": {
          "chainId": "1",
          "tokenIn": {
            "address": "0x0000000000000000000000000000000000000000",
            "name": "ETH",
            "decimals": 18,
            "symbol": "ETH",
            "icon": "https://s3.amazonaws.com/map-static-file/mapSwap/ethereum/0x0000000000000000000000000000000000000000/logo.png"
          },
          "tokenOut": {
            "address": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
            "name": "Wrapped Ether",
            "decimals": 18,
            "symbol": "WETH",
            "icon": "https://s3.amazonaws.com/map-static-file/mapSwap/ethereum/0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2/logo.png"
          },
          "totalAmountIn": "1.0",
          "totalAmountOut": "1.0",
          "route": [
            {
              "amountIn": "1.0",
              "amountOut": "1.0",
              "dexName": "",
              "path": []
            }
          ],
          "totalAmountOutUSD": "3489.33119093",
          "bridge": "Butter"
        },
        "bridgeChain": {
          "chainId": "22776",
          "tokenIn": {
            "address": "0x05aB928d446d8ce6761e368c8e7bE03C3168A9ec",
            "name": "Mapped Wrapped Ether",
            "decimals": 18,
            "symbol": "WETH",
            "icon": "https://s3.amazonaws.com/map-static-file/mapSwap/ethereum/0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2/logo.png"
          },
          "tokenOut": {
            "address": "0x05aB928d446d8ce6761e368c8e7bE03C3168A9ec",
            "name": "Mapped Wrapped Ether",
            "decimals": 18,
            "symbol": "WETH",
            "icon": "https://s3.amazonaws.com/map-static-file/mapSwap/ethereum/0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2/logo.png"
          },
          "totalAmountIn": "1.0",
          "totalAmountOut": "0.99662",
          "route": [
            {
              "amountIn": "1.0",
              "amountOut": "0.99662",
              "dexName": "",
              "path": []
            }
          ],
          "bridge": "Butter"
        },
        "dstChain": {
          "chainId": "56",
          "tokenIn": {
            "address": "0x2170Ed0880ac9A755fd29B2688956BD959F933F8",
            "name": "Wrapped ETH",
            "decimals": 18,
            "symbol": "WETH",
            "icon": "https://s3.amazonaws.com/map-static-file/mapSwap/ethereum/0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2/logo.png"
          },
          "tokenOut": {
            "address": "0x0000000000000000000000000000000000000000",
            "name": "BNB",
            "decimals": 18,
            "symbol": "BNB",
            "icon": "https://s3.amazonaws.com/map-static-file/mapSwap/binance-smart-chain/0x0000000000000000000000000000000000000000/logo.png"
          },
          "totalAmountIn": "0.99662",
          "totalAmountOut": "4.939139219083695572",
          "route": [
            {
              "amountIn": "0.597972",
              "amountOut": "2.963763799469397691",
              "dexName": "PancakeswapV3",
              "path": [
                {
                  "id": "0x62Fcb3C1794FB95BD8B1A97f6Ad5D8a7e4943a1e",
                  "tokenIn": {
                    "address": "0x2170Ed0880ac9A755fd29B2688956BD959F933F8",
                    "name": "Wrapped ETH",
                    "decimals": 18,
                    "symbol": "WETH",
                    "icon": "https://s3.amazonaws.com/map-static-file/mapSwap/ethereum/0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2/logo.png"
                  },
                  "tokenOut": {
                    "address": "0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c",
                    "name": "Wrapped BNB",
                    "decimals": 18,
                    "symbol": "WBNB",
                    "icon": "https://s3.amazonaws.com/map-static-file/mapSwap/binance-smart-chain/0xbb4cdb9cbd36b01bd1cbaebf2de08d9173bc095c/logo.png"
                  },
                  "fee": "100"
                }
              ],
              "priceImpact": "0.0315022"
            },
            {
              "amountIn": "0.398648",
              "amountOut": "1.975375419614297881",
              "dexName": "PancakeswapV3",
              "path": [
                {
                  "id": "0xD0e226f674bBf064f54aB47F42473fF80DB98CBA",
                  "tokenIn": {
                    "address": "0x2170Ed0880ac9A755fd29B2688956BD959F933F8",
                    "name": "Wrapped ETH",
                    "decimals": 18,
                    "symbol": "WETH",
                    "icon": "https://s3.amazonaws.com/map-static-file/mapSwap/ethereum/0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2/logo.png"
                  },
                  "tokenOut": {
                    "address": "0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c",
                    "name": "Wrapped BNB",
                    "decimals": 18,
                    "symbol": "WBNB",
                    "icon": "https://s3.amazonaws.com/map-static-file/mapSwap/binance-smart-chain/0xbb4cdb9cbd36b01bd1cbaebf2de08d9173bc095c/logo.png"
                  },
                  "fee": "500"
                }
              ],
              "priceImpact": "0.0552814"
            }
          ],
          "totalAmountOutUSD": "3477.462882862167",
          "bridge": "Butter"
        },
        "totalAmountInUSD": "3489.33119093",
        "totalAmountOutUSD": "3477.462882862167",
        "contract": "0xEE030ec6F4307411607E55aCD08e628Ae6655B86",
        "minAmountOut": {
          "amount": "4.865052130797440139",
          "symbol": "BNB"
        }
      },
      "txParam": {
        "errno": 0,
        "message": "success",
        "data": [
          {
            "to": "0xEE030ec6F4307411607E55aCD08e628Ae6655B86",
            "data": "0x6e1537da00000000000000000000000000000000000000000000000000000000000000000000000000000000000000002d4c407bbe49438ed859fe965b140dcf1aab71a900000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000de0b6b3a7640000000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000003800000000000000000000000000000000000000000000000000000000000000c600000000000000000000000000000000000000000000000000000000000000c8000000000000000000000000000000000000000000000000000000000000002600000000000000000000000000000000000000000000000000000000000000020000000000000000000000000c02aaa39b223fe8d0a0e5c4f27ead9083c756cc20000000000000000000000002d4c407bbe49438ed859fe965b140dcf1aab71a90000000000000000000000002d4c407bbe49438ed859fe965b140dcf1aab71a90000000000000000000000000000000000000000000000000de0b6b3a764000000000000000000000000000000000000000000000000000000000000000000a0000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000004000000000000000000000000c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2000000000000000000000000c02aaa39b223fe8d0a0e5c4f27ead9083c756cc20000000000000000000000000000000000000000000000000de0b6b3a764000000000000000000000000000000000000000000000000000000000000000000a000000000000000000000000000000000000000000000000000000000000000a00000000000000000000000000000000000000000000000000000000000000040000000000000000000000000000000000000000000000000000000000000006000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004d0e30db00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000008c0000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000380000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000000c00000000000000000000000000000000000000000000000000000000000000014ff0309a8f2a9d9afe040d990bba4ef3512e3288800000000000000000000000000000000000000000000000000000000000000000000000000000000000007c000000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000000000000000000000000000000200aee9ba7040d778922a763ce8a50948d61aff50000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000a000000000000000000000000000000000000000000000000000000000000006e0000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000006c00000000000000000000000000000000000000000000000000000000000000660000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000000000000000000000000000002d4c407bbe49438ed859fe965b140dcf1aab71a90000000000000000000000002d4c407bbe49438ed859fe965b140dcf1aab71a90000000000000000000000000000000000000000000000004384232305f04c8b00000000000000000000000000000000000000000000000000000000000000a0000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000004000000000000000000000000aa301070448385cfaac5913a67b16c4392944a8f000000000000000000000000aa301070448385cfaac5913a67b16c4392944a8f0000000000000000000000000000000000000000000000000dd4b49c140cc00000000000000000000000000000000000000000000000000000000000000000a000000000000000000000000000000000000000000000000000000000000004a00000000000000000000000000000000000000000000000000000000000000040000000000000000000000000000000000000000000000000000000000000006000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000404efa0646500000000000000000000000000000000000000000000000000000000000000200000000000000000000000002170ed0880ac9a755fd29b2688956bd959f933f8000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000002d4c407bbe49438ed859fe965b140dcf1aab71a90000000000000000000000000000000000000000000000004384232305f04c8b00000000000000000000000000000000000000000000000000000000000000c00000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000001a0000000000000000000000000000000000000000000000000000000000000000200000000000000000000000013f4ea83d0bd40e75c8222255bc855a974568dd400000000000000000000000013f4ea83d0bd40e75c8222255bc855a974568dd4000000000000000000000000000000000000000000000000084c6c5da5a1400000000000000000000000000000000000000000000000000000000000000000a000000000000000000000000000000000000000000000000000000000000000a000000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000040000000000000000000000000000000000000000000000000000000000000002b2170ed0880ac9a755fd29b2688956bd959f933f8000064bb4cdb9cbd36b01bd1cbaebf2de08d9173bc095c000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000200000000000000000000000013f4ea83d0bd40e75c8222255bc855a974568dd400000000000000000000000013f4ea83d0bd40e75c8222255bc855a974568dd40000000000000000000000000000000000000000000000000588483e6e6b800000000000000000000000000000000000000000000000000000000000000000a000000000000000000000000000000000000000000000000000000000000000a000000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000040000000000000000000000000000000000000000000000000000000000000002b2170ed0880ac9a755fd29b2688956bd959f933f80001f4bb4cdb9cbd36b01bd1cbaebf2de08d9173bc095c000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000600000000000000000000000000000000000000000000000000000000000000001000000000000000000000000200aee9ba7040d778922a763ce8a50948d61aff50000000000000000000000000000000000000000000000000000000000000000",
            "value": "0x0de0b6b3a7640000",
            "chainId": "1",
            "method": "swapAndBridge",
            "args": [
              {
                "type": "bytes32",
                "value": "0x0000000000000000000000000000000000000000000000000000000000000000"
              },
              {
                "type": "address",
                "value": "0x2D4C407BBe49438ED859fe965b140dcF1aaB71a9"
              },
              {
                "type": "address",
                "value": "0x0000000000000000000000000000000000000000"
              },
              {
                "type": "uint256",
                "value": "1000000000000000000"
              },
              {
                "type": "bytes",
                "value": "0x0000000000000000000000000000000000000000000000000000000000000020000000000000000000000000c02aaa39b223fe8d0a0e5c4f27ead9083c756cc20000000000000000000000002d4c407bbe49438ed859fe965b140dcf1aab71a90000000000000000000000002d4c407bbe49438ed859fe965b140dcf1aab71a90000000000000000000000000000000000000000000000000de0b6b3a764000000000000000000000000000000000000000000000000000000000000000000a0000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000004000000000000000000000000c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2000000000000000000000000c02aaa39b223fe8d0a0e5c4f27ead9083c756cc20000000000000000000000000000000000000000000000000de0b6b3a764000000000000000000000000000000000000000000000000000000000000000000a000000000000000000000000000000000000000000000000000000000000000a00000000000000000000000000000000000000000000000000000000000000040000000000000000000000000000000000000000000000000000000000000006000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004d0e30db000000000000000000000000000000000000000000000000000000000"
              },
              {
                "type": "bytes",
                "value": "0x000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000380000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000000c00000000000000000000000000000000000000000000000000000000000000014ff0309a8f2a9d9afe040d990bba4ef3512e3288800000000000000000000000000000000000000000000000000000000000000000000000000000000000007c000000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000000000000000000000000000000200aee9ba7040d778922a763ce8a50948d61aff50000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000a000000000000000000000000000000000000000000000000000000000000006e0000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000006c00000000000000000000000000000000000000000000000000000000000000660000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000000000000000000000000000002d4c407bbe49438ed859fe965b140dcf1aab71a90000000000000000000000002d4c407bbe49438ed859fe965b140dcf1aab71a90000000000000000000000000000000000000000000000004384232305f04c8b00000000000000000000000000000000000000000000000000000000000000a0000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000004000000000000000000000000aa301070448385cfaac5913a67b16c4392944a8f000000000000000000000000aa301070448385cfaac5913a67b16c4392944a8f0000000000000000000000000000000000000000000000000dd4b49c140cc00000000000000000000000000000000000000000000000000000000000000000a000000000000000000000000000000000000000000000000000000000000004a00000000000000000000000000000000000000000000000000000000000000040000000000000000000000000000000000000000000000000000000000000006000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000404efa0646500000000000000000000000000000000000000000000000000000000000000200000000000000000000000002170ed0880ac9a755fd29b2688956bd959f933f8000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000002d4c407bbe49438ed859fe965b140dcf1aab71a90000000000000000000000000000000000000000000000004384232305f04c8b00000000000000000000000000000000000000000000000000000000000000c00000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000001a0000000000000000000000000000000000000000000000000000000000000000200000000000000000000000013f4ea83d0bd40e75c8222255bc855a974568dd400000000000000000000000013f4ea83d0bd40e75c8222255bc855a974568dd4000000000000000000000000000000000000000000000000084c6c5da5a1400000000000000000000000000000000000000000000000000000000000000000a000000000000000000000000000000000000000000000000000000000000000a000000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000040000000000000000000000000000000000000000000000000000000000000002b2170ed0880ac9a755fd29b2688956bd959f933f8000064bb4cdb9cbd36b01bd1cbaebf2de08d9173bc095c000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000200000000000000000000000013f4ea83d0bd40e75c8222255bc855a974568dd400000000000000000000000013f4ea83d0bd40e75c8222255bc855a974568dd40000000000000000000000000000000000000000000000000588483e6e6b800000000000000000000000000000000000000000000000000000000000000000a000000000000000000000000000000000000000000000000000000000000000a000000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000040000000000000000000000000000000000000000000000000000000000000002b2170ed0880ac9a755fd29b2688956bd959f933f80001f4bb4cdb9cbd36b01bd1cbaebf2de08d9173bc095c000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000"
              },
              {
                "type": "bytes",
                "value": "0x"
              },
              {
                "type": "bytes",
                "value": "0x0000000000000000000000000000000000000000000000000000000000000001000000000000000000000000200aee9ba7040d778922a763ce8a50948d61aff50000000000000000000000000000000000000000000000000000000000000000"
              }
            ]
          }
        ]
      }
    }
  ]
}

1. fail to get route and/or swap transaction calldata

200 Response

{
    "errno": <error code>,
    "message": <detailed error message>
}

Note: error code can be found in here