Skip to content

README.md

Latest commit

 

History

History
158 lines (117 loc) · 3.4 KB

README.md

File metadata and controls

158 lines (117 loc) · 3.4 KB

SwapAPI MCP Server

MCP (Model Context Protocol) server for SwapAPI. Enables AI agents to get executable token swap calldata for any EVM chain.

Installation

npm install -g @swapapi/mcp

Or use directly with npx:

npx @swapapi/mcp

Client Configuration

Claude Desktop

Add to your Claude Desktop config:

{
  "mcpServers": {
    "swapapi": {
      "command": "npx",
      "args": ["@swapapi/mcp"]
    }
  }
}

Or with a local install:

{
  "mcpServers": {
    "swapapi": {
      "command": "npx",
      "args": ["tsx", "/path/to/swap-api/mcp/mcp-server.ts"]
    }
  }
}

Cursor

Add to your Cursor settings (Settings → MCP):

{
  "mcpServers": {
    "swapapi": {
      "command": "npx",
      "args": ["@swapapi/mcp"]
    }
  }
}

Other Clients

Any MCP-compatible client can use the same configuration format. Check your client's documentation for where to add MCP server settings.

Available Tools

swap_tokens

Get executable transaction data to swap tokens on EVM chains.

Parameters:

Parameter Type Required Description
chainId number Yes Chain ID (1=Ethereum, 8453=Base, 42161=Arbitrum, etc.)
tokenIn string Yes Input token address. Use 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE for native token (ETH, MATIC, etc.)
tokenOut string Yes Output token address
amountIn string Yes Amount in smallest unit (wei for 18-decimal tokens, micro-units for 6-decimal tokens)
sender string Yes Wallet address that will sign and send the transaction
maxSlippage number No Max slippage tolerance 0-1 (default: 0.005 = 0.5%)

Returns:

{
  "to": "0x...",           // Router contract address to call
  "data": "0x...",         // ABI-encoded swap calldata
  "value": "1000000000000000000",  // Native token value (if swapping from native)
  "gas": "150000",         // Estimated gas limit
  "guaranteedOut": "..."   // Minimum output amount after slippage
}

Examples

Swap 0.001 ETH to USDC on Base

{
  "chainId": 8453,
  "tokenIn": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
  "tokenOut": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "amountIn": "1000000000000000",
  "sender": "0xYourAddress"
}

Swap USDC to ETH on Arbitrum with 1% slippage

{
  "chainId": 42161,
  "tokenIn": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
  "tokenOut": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
  "amountIn": "10000000",
  "sender": "0xYourAddress",
  "maxSlippage": 0.01
}

Pre-flight Checklist

Before submitting any swap transaction:

  1. ERC-20 Approval: If tokenIn is not native token, ensure sender has approved the router for at least amountIn
  2. Balance Check: Verify sender has sufficient balance for amountIn (plus value if native token)
  3. Gas Estimation: Call eth_estimateGas on the transaction and add 20% buffer
  4. Simulation: Run eth_call to verify the transaction won't revert
  5. Timing: Submit within 30 seconds of fetching the quote (calldata has expiry)

See the main README.md for full API documentation.

Development

cd mcp
npm install
npm start

Testing

Run the test suite:

npm test

Or use the MCP Inspector:

npx @modelcontextprotocol/inspector tsx mcp-server.ts

License

MIT