Butter Swap

Butter Swap

This skill provides integration with Butter Router API for cross-chain token swaps. It aggregates DEX routes across multiple chains to find optimal swap paths.

Base URL

BASE_URL=https://bs-router-v3.chainservice.io

All API endpoints use {BASE_URL} as the base.

API Response Format

All responses follow this structure:

{
  "errno": 0,
  "message": "success",
  "data": [{ ... }]  // data is an array
}

Note: The data field is always an array [{...}], not an object.

Common Use Cases

1. Get Supported Chains

Goal: Find out which blockchains are supported for cross-chain swaps.

Endpoint: GET /supportedChainInfo

Example:

curl -X GET "{BASE_URL}/supportedChainInfo"

2. Find Token Information

Goal: Look up token details by contract address.

Endpoint: GET /findToken

Example:

curl -X GET "{BASE_URL}/findToken?address=0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599"

Response includes: chainId, address, name, symbol, decimals, usdPrice, image

3. Get Swap Route

Goal: Query optimal routes for cross-chain token swaps and get quote.

Endpoint: GET /route

Parameters:

Example:

curl -X GET "{BASE_URL}/route?fromChainId=1&toChainId=56&amount=100&tokenInAddress=0xdAC17F958D2ee523a2206206994597C13D831ec7&tokenOutAddress=0x55d398326f99059fF775485246999027B3197955&type=exactIn&slippage=100&entrance=agent"

Note: Use human-readable amount (e.g., "100" for 100 USDT), NOT wei units. If the entrance parameter is not provided, it defaults to "agent".

Response includes:

• hash: Route identifier for getting swap transaction
• amountIn / amountOut: Expected input/output amounts
• bridgeFee: Fee for bridging
• gasFee: Estimated gas cost
• srcChain / dstChain: Chain details with token addresses

4. Get Swap Transaction

Goal: Assemble transaction data for executing a swap using the route hash.

Endpoint: GET /swap

Parameters:

Example:

curl -X GET "{BASE_URL}/swap?hash=0xabc123...&slippage=100&from=0x123...&receiver=0x456..."

Response includes:

• to: Contract address to call
• data: Calldata for the transaction
• value: Native token value to send (if any)
• chainId: Target chain ID

5. Get Complete Swap (Route + Swap TX)

Goal: Get route and swap transaction data in one call.

Endpoint: GET /routeAndSwap

Combines /route and /swap endpoints. Parameters are the same as /route plus from and receiver.

Example:

curl -X GET "{BASE_URL}/routeAndSwap?fromChainId=1&toChainId=56&amount=100&tokenInAddress=0xdAC17F958D2ee523a2206206994597C13D831ec7&tokenOutAddress=0x55d398326f99059fF775485246999027B3197955&type=exactIn&slippage=100&entrance=agent&from=0xA015d9e9206859c13201BB3D6B324d6634276534&receiver=0xA015d9e9206859c13201BB3D6B324d6634276534"

Response includes:

• route: Same as /route response
• txParam: Transaction data (to, data, value, chainId)
• error: If swap fails, contains error details

Common Workflows

Cross-Chain Swap Flow

1. Get supported chains: Call /supportedChainInfo to see available networks
2. Find tokens: Use /findToken to get token addresses and decimals
3. Get quote: Call /route to get optimal route and expected output
4. Get transaction: Use hash from route to call /swap for transaction data
5. Execute: User signs and submits the transaction

One-Call Swap

Use /routeAndSwap to skip step 3-4 and get everything in one request.

Common Chain IDs

MCP Tools

This skill uses butter-router-mcp for tool-based access:

get_supported_chain_info

Query all supported blockchains.

find_token

Find token information by token address.

get_route

Query best routes for cross-chain token swap.

• fromChainId: Source chain ID
• toChainId: Destination chain ID
• amount: Amount in human readable format (e.g., "100" for 100 USDT, NOT wei)
• tokenInAddress: Input token address (use 0x000...0000 for native)
• tokenOutAddress: Output token address
• type: "exactIn" or "exactOut"
• slippage: Slippage in bps (default: 100 = 1%)
• entrance: Required, must be "agent"

Important: The response data is an array that may contain multiple routes. You MUST handle this as follows:

1. If data.length === 0: No routes found - inform user
2. If data.length === 1: Use the single route
3. If data.length > 1: Present all routes to user for selection

When multiple routes are available, display each route with:

• Route index (1, 2, 3...)
• hash: Route identifier
• bridgeFee: Bridge fee amount and symbol
• gasFee: Gas fee amount and symbol
• dex: The DEX exchange path used (e.g., "UniV3 > PancakeV3")
• srcChain.totalAmountIn: Input amount
• dstChain.totalAmountOut: Output amount (after fees)
• minAmountOut: Minimum output amount (with slippage protection)

Always include the dex field in the display - this shows which DEX or path was used for the swap.

Then ask user to select which route to use by entering the route number (1, 2, 3...).

After user selects a route, use the selected route's hash to call get_swap for transaction data.

When calling get_swap, ask user for slippage preference:

• If user specifies slippage (e.g., 100 = 1%, 50 = 0.5%, 500 = 5%), use that value
• If user does not specify, use default slippage = 100 (1%)

get_swap

Assemble transaction data based on route hash.

Parameters:

Display real transaction data to user, including:

• to: Contract address to call
• data: Full calldata (show full hex, not truncated)
• value: Native token value in hex and human readable
• chainId: Target chain ID
• method: Contract method name

Example Response

Route Response

{
  "errno": 0,
  "message": "success",
  "data": [
    {
      "hash": "0xcbb224a6ecb83a32a17643877941d27df226784be9688ba8f7833f256c5170ec",
      "bridgeFee": { "amount": "0.449954", "symbol": "USDT" },
      "gasFee": { "amount": "0.00006751415372", "symbol": "ETH" },
      "dex": "UniV3 > PancakeV3",
      "srcChain": {
        "chainId": "1",
        "totalAmountIn": "100.0",
        "totalAmountOut": "100.0"
      },
      "dstChain": {
        "chainId": "56",
        "totalAmountIn": "99.550046",
        "totalAmountOut": "99.550046"
      },
      "minAmountOut": { "amount": "99.550046", "symbol": "USDT" }
    }
  ]
}

Swap Transaction

{
  "errno": 0,
  "message": "success",
  "data": [
    {
      "to": "0xEE0319cF0BCa5d09333f9F6277743E8De31bD69A",
      "data": "0x6e1537da000000000000000000000000766f3377497C66c31a5692A435cF3E72Dcc2d4Fc000000000000000000000000766f3377497C66c31a5692A435cF3E72Dcc2d4Fc...",
      "value": "0x0f43fc2c04ee0000",
      "chainId": "1",
      "method": "swapAndBridge"
    }
  ]
}

Common Errors

API Documentation

For detailed API documentation, visit: https://docs.butternetwork.io/butter-swap-integration/integration-guide