\r \r

Butter Swap\r

\r 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.\r \r

Base URL\r

\r

BASE_URL=https://bs-router-v3.chainservice.io\r
```\r
\r
All API endpoints use `{BASE_URL}` as the base.\r
\r
## API Response Format\r
\r
All responses follow this structure:\r
\r
```json\r
{\r
  "errno": 0,\r
  "message": "success",\r
  "data": [{ ... }]  // data is an array\r
}\r
```\r
\r
**Note:** The `data` field is always an array `[{...}]`, not an object.\r
\r
| errno | Meaning                                                       |\r
| ----- | ------------------------------------------------------------- |\r
| 0     | Success                                                       |\r
| 2000  | Parameter error (e.g., missing entrance parameter)            |\r
| 2003  | No Route Found (liquidity insufficient or pair not supported) |\r
| 2004  | Insufficient Liquidity (amount exceeds max)                   |\r
| other | Error (check message)                                         |\r
\r
## Common Use Cases\r
\r
### 1. Get Supported Chains\r
\r
**Goal:** Find out which blockchains are supported for cross-chain swaps.\r
\r
**Endpoint:** `GET /supportedChainInfo`\r
\r
**Example:**\r
\r
```bash\r
curl -X GET "{BASE_URL}/supportedChainInfo"\r
```\r
\r
---\r
\r
### 2. Find Token Information\r
\r
**Goal:** Look up token details by contract address.\r
\r
**Endpoint:** `GET /findToken`\r
\r
**Example:**\r
\r
```bash\r
curl -X GET "{BASE_URL}/findToken?address=0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599"\r
```\r
\r
**Response includes:** chainId, address, name, symbol, decimals, usdPrice, image\r
\r
---\r
\r
### 3. Get Swap Route\r
\r
**Goal:** Query optimal routes for cross-chain token swaps and get quote.\r
\r
**Endpoint:** `GET /route`\r
\r
**Parameters:**\r
\r
| Parameter       | Type   | Required | Description                                                                       |\r
| --------------- | ------ | -------- | --------------------------------------------------------------------------------- |\r
| fromChainId     | number | Yes      | Source chain ID (e.g., 1 for Ethereum, 56 for BSC)                                |\r
| toChainId       | number | Yes      | Destination chain ID                                                              |\r
| amount          | string | Yes      | Amount to swap (human readable, e.g., "100" for 100 USDT, NOT wei)                |\r
| tokenInAddress  | string | Yes      | Input token address (use `0x0000000000000000000000000000000000000000` for native) |\r
| tokenOutAddress | string | Yes      | Output token address on destination chain                                         |\r
| type            | string | No       | "exactIn" or "exactOut" (default: exactIn)                                        |\r
| slippage        | number | No       | Slippage in bps, default 100 (1%)                                                 |\r
| entrance        | string | No       | Router entrance (default: "agent")                                                |\r
\r
**Example:**\r
\r
```bash\r
curl -X GET "{BASE_URL}/route?fromChainId=1&toChainId=56&amount=100&tokenInAddress=0xdAC17F958D2ee523a2206206994597C13D831ec7&tokenOutAddress=0x55d398326f99059fF775485246999027B3197955&type=exactIn&slippage=100&entrance=agent"\r
```\r
\r
**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".\r
\r
**Response includes:**\r
\r
- `hash`: Route identifier for getting swap transaction\r
- `amountIn` / `amountOut`: Expected input/output amounts\r
- `bridgeFee`: Fee for bridging\r
- `gasFee`: Estimated gas cost\r
- `srcChain` / `dstChain`: Chain details with token addresses\r
\r
---\r
\r
### 4. Get Swap Transaction\r
\r
**Goal:** Assemble transaction data for executing a swap using the route hash.\r
\r
**Endpoint:** `GET /swap`\r
\r
**Parameters:**\r
\r
| Parameter | Type   | Required | Description                              |\r
| --------- | ------ | -------- | ---------------------------------------- |\r
| hash      | string | Yes      | Route hash from /route response          |\r
| from      | string | Yes      | Sender wallet address                    |\r
| receiver  | string | Yes      | Receiver address                         |\r
| slippage  | number | no       | Slippage in bps (100 = 1%, default: 100) |\r
\r
**Example:**\r
\r
```bash\r
curl -X GET "{BASE_URL}/swap?hash=0xabc123...&slippage=100&from=0x123...&receiver=0x456..."\r
```\r
\r
**Response includes:**\r
\r
- `to`: Contract address to call\r
- `data`: Calldata for the transaction\r
- `value`: Native token value to send (if any)\r
- `chainId`: Target chain ID\r
\r
---\r
\r
### 5. Get Complete Swap (Route + Swap TX)\r
\r
**Goal:** Get route and swap transaction data in one call.\r
\r
**Endpoint:** `GET /routeAndSwap`\r
\r
Combines `/route` and `/swap` endpoints. Parameters are the same as `/route` plus `from` and `receiver`.\r
\r
**Example:**\r
\r
```bash\r
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"\r
```\r
\r
**Response includes:**\r
\r
- `route`: Same as /route response\r
- `txParam`: Transaction data (to, data, value, chainId)\r
- `error`: If swap fails, contains error details\r
\r
---\r
\r
## Common Workflows\r
\r
### Cross-Chain Swap Flow\r
\r
1. **Get supported chains**: Call `/supportedChainInfo` to see available networks\r
2. **Find tokens**: Use `/findToken` to get token addresses and decimals\r
3. **Get quote**: Call `/route` to get optimal route and expected output\r
4. **Get transaction**: Use hash from route to call `/swap` for transaction data\r
5. **Execute**: User signs and submits the transaction\r
\r
### One-Call Swap\r
\r
Use `/routeAndSwap` to skip step 3-4 and get everything in one request.\r
\r
---\r
\r
## Common Chain IDs\r
\r
| Chain     | Chain ID |\r
| --------- | -------- |\r
| Ethereum  | 1        |\r
| BSC       | 56       |\r
| Polygon   | 137      |\r
| Arbitrum  | 42161    |\r
| Optimism  | 10       |\r
| Base      | 8453     |\r
| Avalanche | 43114    |\r
| Solana    | 7560     |\r
\r
---\r
\r
## MCP Tools\r
\r
This skill uses butter-router-mcp for tool-based access:\r
\r
### get_supported_chain_info\r
\r
Query all supported blockchains.\r
\r
### find_token\r
\r
Find token information by token address.\r
\r
### get_route\r
\r
Query best routes for cross-chain token swap.\r
\r
- `fromChainId`: Source chain ID\r
- `toChainId`: Destination chain ID\r
- `amount`: Amount in human readable format (e.g., "100" for 100 USDT, NOT wei)\r
- `tokenInAddress`: Input token address (use `0x000...0000` for native)\r
- `tokenOutAddress`: Output token address\r
- `type`: "exactIn" or "exactOut"\r
- `slippage`: Slippage in bps (default: 100 = 1%)\r
- `entrance`: Required, must be "agent"\r
\r
**Important:** The response `data` is an **array** that may contain multiple routes. You MUST handle this as follows:\r
\r
1. If `data.length === 0`: No routes found - inform user\r
2. If `data.length === 1`: Use the single route\r
3. If `data.length > 1`: Present all routes to user for selection\r
\r
**When multiple routes are available, display each route with:**\r
\r
- Route index (1, 2, 3...)\r
- `hash`: Route identifier\r
- `bridgeFee`: Bridge fee amount and symbol\r
- `gasFee`: Gas fee amount and symbol\r
- `dex`: The DEX exchange path used (e.g., "UniV3 > PancakeV3")\r
- `srcChain.totalAmountIn`: Input amount\r
- `dstChain.totalAmountOut`: Output amount (after fees)\r
- `minAmountOut`: Minimum output amount (with slippage protection)\r
\r
**Always include the `dex` field in the display - this shows which DEX or path was used for the swap.**\r
\r
**Then ask user to select** which route to use by entering the route number (1, 2, 3...).\r
\r
After user selects a route, use the selected route's `hash` to call `get_swap` for transaction data.\r
\r
**When calling get_swap, ask user for slippage preference:**\r
\r
- If user specifies slippage (e.g., 100 = 1%, 50 = 0.5%, 500 = 5%), use that value\r
- If user does not specify, use default slippage = 100 (1%)\r
\r
### get_swap\r
\r
Assemble transaction data based on route hash.\r
\r
**Parameters:**\r
\r
| Parameter    | Type   | Required | Default | Description                                       |\r
| ------------ | ------ | -------- | ------- | ------------------------------------------------- |\r
| hash         | string | Yes      | -       | Route hash from getRoute response                 |\r
| slippage     | number | No       | 100     | Slippage in bps (e.g., 100 = 1%)                  |\r
| from         | string | Yes      | -       | Sender wallet address                             |\r
| receiver     | string | Yes      | -       | Receiver address on destination chain             |\r
| refundAddr   | string | No       | from    | Refund address if transaction fails               |\r
| feeToken     | string | No       | -       | Address of token to pay protocol fees (optional)  |\r
| destGasLimit | string | No       | -       | Custom gas limit for destination chain (optional) |\r
\r
**Display real transaction data to user, including:**\r
\r
- `to`: Contract address to call\r
- `data`: Full calldata (show full hex, not truncated)\r
- `value`: Native token value in hex and human readable\r
- `chainId`: Target chain ID\r
- `method`: Contract method name\r
\r
---\r
\r
## Example Response\r
\r
### Route Response\r
\r
```json\r
{\r
  "errno": 0,\r
  "message": "success",\r
  "data": [\r
    {\r
      "hash": "0xcbb224a6ecb83a32a17643877941d27df226784be9688ba8f7833f256c5170ec",\r
      "bridgeFee": { "amount": "0.449954", "symbol": "USDT" },\r
      "gasFee": { "amount": "0.00006751415372", "symbol": "ETH" },\r
      "dex": "UniV3 > PancakeV3",\r
      "srcChain": {\r
        "chainId": "1",\r
        "totalAmountIn": "100.0",\r
        "totalAmountOut": "100.0"\r
      },\r
      "dstChain": {\r
        "chainId": "56",\r
        "totalAmountIn": "99.550046",\r
        "totalAmountOut": "99.550046"\r
      },\r
      "minAmountOut": { "amount": "99.550046", "symbol": "USDT" }\r
    }\r
  ]\r
}\r
```\r
\r
### Swap Transaction\r
\r
```json\r
{\r
  "errno": 0,\r
  "message": "success",\r
  "data": [\r
    {\r
      "to": "0xEE0319cF0BCa5d09333f9F6277743E8De31bD69A",\r
      "data": "0x6e1537da000000000000000000000000766f3377497C66c31a5692A435cF3E72Dcc2d4Fc000000000000000000000000766f3377497C66c31a5692A435cF3E72Dcc2d4Fc...",\r
      "value": "0x0f43fc2c04ee0000",\r
      "chainId": "1",\r
      "method": "swapAndBridge"\r
    }\r
  ]\r
}\r
```\r
\r
### Common Errors\r
\r
| errno | Message                           | Solution                                    |\r
| ----- | --------------------------------- | ------------------------------------------- |\r
| 2000  | Parameter error: Missing entrance | Add `entrance=Butter%2B` parameter          |\r
| 2003  | No Route Found                    | Try different token pair or chain           |\r
| 2004  | Insufficient Liquidity            | Amount exceeds max liquidity, reduce amount |\r
\r
### API Documentation\r
\r
For detailed API documentation, visit: https://docs.butternetwork.io/butter-swap-integration/integration-guide\r