cli-swap

Multi-chain token swap CLI for humans and AI agents. Powered by Li.Fi SDK (60+ chains).

The open-source DeFi toolkit for AI agents. Swap any token on 60+ chains via CLI, MCP, or HTTP API.

Features

60+ chains: Ethereum, Solana, Polygon, Arbitrum, Base, BSC, Optimism, Avalanche, and more
Swap & Send: Swap tokens or send to any address (native + ERC-20/SPL)
3 integration modes: CLI, MCP Server (Claude native), HTTP REST API
Agent mode: Natural language swaps — cli-swap agent "swap 1 ETH to USDC"
Batch swaps: Execute multiple swaps from a JSON file
AI SDK examples: Claude Agent SDK, LangChain, Vercel AI SDK
OpenClaw integration: Swap tokens from Telegram, WhatsApp, Slack via OpenClaw AI agent
Secure wallet storage: AES-256-GCM encrypted private keys stored locally
Best route: Li.Fi aggregates 20+ DEXs and 20+ bridges for optimal pricing

Install

npm install -g cli-swap

# or run directly
npx cli-swap --help

Quick Start

# 1. Import your wallet
cli-swap wallet import --name my-wallet --type evm

# 2. Check supported chains
cli-swap chains

# 3. Search tokens
cli-swap tokens ethereum USDC

# 4. Get a quote
cli-swap quote ethereum USDC polygon USDC 100

# 5. Execute swap
cli-swap swap ethereum USDC polygon USDC 100 --slippage 1

Commands

Wallet Management

cli-swap wallet import          # Import wallet (interactive)
cli-swap wallet import --name w1 --type evm --key 0x... --password mypass
cli-swap wallet list            # List saved wallets
cli-swap wallet remove <name>   # Remove a wallet
cli-swap wallet default <name>  # Set default wallet

Information

cli-swap chains                           # List all 60+ supported chains
cli-swap chains --type EVM                # Filter by chain type (EVM/SVM)
cli-swap tokens <chain> [query]           # Search tokens on a chain
cli-swap balance <chain>                  # Check native token balance

Configuration

cli-swap config show                      # Show current config
cli-swap config set-rpc <chainId> <url>   # Set custom RPC URL
cli-swap config remove-rpc <chainId>      # Remove custom RPC URL
cli-swap config set-slippage <pct>        # Set default slippage (e.g. 0.5)

Swap

# Get quote only (no execution)
cli-swap quote <fromChain> <fromToken> <toChain> <toToken> <amount>

# Execute swap
cli-swap swap <fromChain> <fromToken> <toChain> <toToken> <amount> [options]

Options:

Flag	Description
`--slippage <pct>`	Slippage tolerance in % (default: 0.5)
`--wallet <name>`	Wallet to use (default: default wallet)
`--password <pw>`	Wallet password (or use `SWAP_WALLET_PASSWORD` env)
`--yes`	Skip confirmation prompt
`--json`	Output as JSON

Send (Transfer)

# Send native tokens
cli-swap send <chain> <token> <toAddress> <amount> [options]

Examples:

# Send ETH on Ethereum
cli-swap send ethereum ETH 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68 0.5

# Send USDC (ERC-20) on Polygon
cli-swap send polygon USDC 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68 100

# Send SOL on Solana
cli-swap send solana SOL 7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU 2.5

# Non-interactive (for AI agents)
cli-swap send ethereum ETH 0x742d...f2bD68 0.5 --wallet main --password mypass --yes --json

Options: Same as swap (--wallet, --password, --yes, --json)

Examples

# Same-chain swap: ETH → USDC on Ethereum
cli-swap swap ethereum ETH ethereum USDC 0.5

# Cross-chain swap: USDC from Ethereum to Polygon
cli-swap swap ethereum USDC polygon USDC 100 --slippage 1

# Solana: SOL → USDC
cli-swap swap solana SOL solana USDC 5

# Cross-ecosystem: Solana SOL → Ethereum USDC
cli-swap swap solana SOL ethereum USDC 5

Agent Mode (Natural Language)

# Natural language swap
cli-swap agent "swap 1 ETH to USDC on ethereum"
cli-swap agent "이더리움 ETH 0.5개를 USDC로 바꿔줘"
cli-swap agent "bridge 100 USDC from ethereum to polygon"

# Natural language send/transfer
cli-swap agent "send 0.5 ETH to 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68 on ethereum"
cli-swap agent "이더리움에서 USDC 100개를 0x742d...로 보내줘"

# Non-interactive (for automation)
cli-swap agent "swap 1 ETH to USDC on ethereum" --wallet main --password mypass --yes --json
cli-swap agent "send 0.5 ETH to 0x742d...f2bD68 on ethereum" --wallet main --password mypass --yes --json

Batch Swaps

Execute multiple swaps from a JSON file:

# Preview (dry run)
cli-swap batch swaps.json --dry-run

# Execute all
cli-swap batch swaps.json --wallet main --password mypass

# Continue even if one fails
cli-swap batch swaps.json --continue-on-error --json

swaps.json:

[
  { "fromChain": "ethereum", "fromToken": "ETH", "toChain": "ethereum", "toToken": "USDC", "amount": "0.1" },
  { "fromChain": "ethereum", "fromToken": "USDC", "toChain": "polygon", "toToken": "USDC", "amount": "50" }
]

AI Agent Integration

The CLI is designed to be called programmatically by AI agents:

# Non-interactive mode: JSON output + auto-confirm + password via env
export SWAP_WALLET_PASSWORD=mypassword
cli-swap swap ethereum USDC polygon USDC 100 --yes --json

# Output:
# {
#   "status": "success",
#   "txHash": "0x...",
#   "from": { "chain": "Ethereum", "token": "USDC", "amount": "100.000000" },
#   "to": { "chain": "Polygon", "token": "USDC", "amount": "99.950000" },
#   "explorerUrl": "https://etherscan.io/tx/0x..."
# }

Key flags for automation:

--json: All output as parseable JSON (both success and errors)
--yes: Skip confirmation prompts
--password <pw> or SWAP_WALLET_PASSWORD env: Non-interactive password
Exit codes: 0 = success, 1 = failure

Error response (JSON):

{
  "status": "failed",
  "error": "Wallet \"main\" not found. Run `cli-swap wallet list` to see available wallets."
}

MCP Server (AI Agent Native Integration)

cli-swap includes a built-in MCP server that exposes swap functionality as native tools for AI agents like Claude.

Available MCP Tools

Tool	Description
`list_chains`	List all 60+ supported chains
`search_tokens`	Search tokens on a chain by symbol/name
`get_balance`	Check native token balance
`get_quote`	Get swap quote (no execution)
`execute_swap`	Execute a token swap
`send_token`	Send tokens to an address (native + ERC-20)
`list_wallets`	List saved wallets
`import_wallet`	Import a new wallet

Setup for Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "cli-swap": {
      "command": "npx",
      "args": ["-y", "cli-swap-mcp"]
    }
  }
}

Or if installed from source:

{
  "mcpServers": {
    "cli-swap": {
      "command": "node",
      "args": ["C:/path/to/cli-swap/dist/mcp-server.js"]
    }
  }
}

Setup for Claude Code

claude mcp add cli-swap -- npx -y cli-swap-mcp

Or from source:

claude mcp add cli-swap -- npx tsx C:/path/to/cli-swap/src/mcp-server.ts

Usage with AI Agent

Once connected, the AI agent can directly call tools:

"이더리움에서 USDC 토큰 검색해줘" → search_tokens(chain: "ethereum", query: "USDC")

"내 지갑 잔액 확인해줘" → get_balance(chain: "ethereum", wallet: "main")

"이더리움 ETH를 아비트럼 USDC로 0.1개 스왑해줘" → execute_swap(...)

SDK Integration Examples

Ready-to-run examples in the examples/ directory:

File	SDK	Description
`claude-agent-sdk.ts`	Claude Agent SDK	Claude as a DeFi trading agent
`langchain.ts`	LangChain	OpenAI Functions Agent + cli-swap HTTP API
`vercel-ai-sdk.ts`	Vercel AI SDK	Multi-step tool calling with any LLM
`batch-swap.json`	—	Example batch swap file

# Claude Agent SDK
ANTHROPIC_API_KEY=sk-... npx tsx examples/claude-agent-sdk.ts

# LangChain (start HTTP API first)
npx cli-swap-api &
OPENAI_API_KEY=sk-... npx tsx examples/langchain.ts

# Vercel AI SDK
npx cli-swap-api &
OPENAI_API_KEY=sk-... npx tsx examples/vercel-ai-sdk.ts

HTTP API Server

For AI agents and services that don't support MCP, cli-swap also provides a REST API:

# Start HTTP API server
npx cli-swap-api                          # port 3100 (default)
npx cli-swap-api --port 8080              # custom port
npx cli-swap-api --api-key mysecretkey    # with API key auth

Endpoints

Method	Path	Description
`GET`	`/health`	Health check
`GET`	`/chains?type=EVM`	List chains
`GET`	`/tokens/:chain?query=USDC`	Search tokens
`GET`	`/balance/:chain?wallet=name`	Check balance
`POST`	`/quote`	Get swap quote
`POST`	`/swap`	Execute swap
`POST`	`/send`	Send tokens to address
`GET`	`/wallets`	List wallets
`POST`	`/wallets`	Import wallet

Example

# Get a swap quote
curl -X POST http://localhost:3100/quote \
  -H "Content-Type: application/json" \
  -d '{"fromChain":"ethereum","fromToken":"ETH","toChain":"ethereum","toToken":"USDC","amount":"1","wallet":"main"}'

OpenClaw Integration (Telegram / WhatsApp / Slack)

Use cli-swap from any messaging app via OpenClaw — the open-source AI agent.

Quick Setup

# 1. Install cli-swap & import wallet
npm install -g cli-swap
cli-swap wallet import --name main --type evm

# 2. Install the OpenClaw skill
cp -r node_modules/cli-swap/openclaw-skill/ ~/.openclaw/workspace/skills/cli-swap/

# 3. Or use MCP Server (recommended)
# Add to ~/.openclaw/config.yaml:

mcp:
  servers:
    cli-swap:
      command: npx
      args: ["-y", "cli-swap-mcp"]

# 4. Set wallet password for non-interactive use
echo 'SWAP_WALLET_PASSWORD=your-password' >> ~/.openclaw/.env

Usage via Telegram

You: swap 1 ETH to USDC on ethereum
Bot: 📊 Quote: 1 ETH → 2,487.32 USDC (via Uniswap V3)
     Fee: ~$2.50 | Slippage: 0.5%
     Proceed? (yes/no)
You: yes
Bot: ✅ Swap executed! TX: 0xabc...123
     🔗 https://etherscan.io/tx/0xabc...123

You: 이더리움 ETH 0.5개를 USDC로 바꿔줘
Bot: 📊 견적: 0.5 ETH → 1,243.66 USDC
     진행할까요?
You: 응
Bot: ✅ 스왑 완료! TX: 0xdef...456

Security: Private keys are stored AES-256-GCM encrypted on your local machine. Only the wallet password is needed at swap time. Never send private keys via Telegram — always import via CLI.

See openclaw-skill/README.md for the full setup guide.

Security

Private keys are encrypted with AES-256-GCM using scrypt-derived keys
Encrypted wallets stored at ~/.cli-swap/wallets/
Keys are never logged or printed
Password required to unlock for every swap

Configuration

Config file: ~/.cli-swap/config.json

{
  "defaultWallet": "main",
  "defaultSlippage": 0.5,
  "rpcOverrides": {
    "1": "https://my-custom-rpc.com"
  }
}

Setting	Default	Description
`defaultWallet`	—	Wallet used when `--wallet` is omitted
`defaultSlippage`	`0.5`	Slippage tolerance in %
`rpcOverrides`	`{}`	Custom RPC URLs keyed by chain ID

Supported Chains

60+ chains including: Ethereum, Solana, Polygon, Arbitrum, Optimism, Base, BSC, Avalanche, Gnosis, Fantom, zkSync, Linea, Scroll, Blast, Mantle, Mode, Celo, and many more.

Run cli-swap chains for the full list.

Development

git clone https://github.com/jeonghwanko/cli-swap.git
cd cli-swap
npm install

# Dev mode (auto-reload)
npm run dev -- wallet list

# Build
npm run build

# Run tests (41 tests across 5 suites)
npm test

# Type check
npx tsc --noEmit

Tech Stack

Component	Technology
CLI framework	Commander.js
MCP Server	@modelcontextprotocol/sdk
Swap aggregator	Li.Fi SDK (60+ chains)
EVM	ethers.js v6
Solana	@solana/web3.js
Encryption	Node.js crypto (AES-256-GCM + scrypt)
Testing	Vitest 4
Language	TypeScript (strict, ESM)

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 12 Commits
.claude		.claude
.github/workflows		.github/workflows
examples		examples
openclaw-skill		openclaw-skill
src		src
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

cli-swap

Features

Install

Quick Start

Commands

Wallet Management

Information

Configuration

Swap

Send (Transfer)

Examples

Agent Mode (Natural Language)

Batch Swaps

AI Agent Integration

MCP Server (AI Agent Native Integration)

Available MCP Tools

Setup for Claude Desktop

Setup for Claude Code

Usage with AI Agent

SDK Integration Examples

HTTP API Server

Endpoints

Example

OpenClaw Integration (Telegram / WhatsApp / Slack)

Quick Setup

Usage via Telegram

Security

Configuration

Supported Chains

Development

Tech Stack

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages