paean-dex-mcp

DEX trading MCP server — autonomous token swaps on Base (Uniswap v3) & Solana (Jupiter) for AI agents.

⚠ AI-Generated Software — Use at Your Own Risk

This software was generated with AI assistance. It has not been independently audited for security vulnerabilities. Cryptocurrency trading involves significant financial risk, including total loss of funds. DEX swaps are irreversible on-chain transactions. The authors and contributors accept no liability for any loss of funds, failed transactions, slippage losses, smart contract exploits, or any other damages resulting from use of this software. Before using with real wallets or mainnet assets, you should conduct your own security review, test thoroughly on testnet, and never trade more than you can afford to lose.

paean-dex-mcp is a Model Context Protocol server that exposes DEX trading operations as tools for AI agents. It enables agents to query token prices, get swap quotes, and execute trades on Base and Solana — without embedding any credentials in prompts or tool outputs.

Chains supported:

• Base — Uniswap v3 (QuoterV2 + SwapRouter02)
• Solana — Jupiter aggregator v6 (optimal routing across all major DEXes)

Privacy-first design:

• Private keys and mnemonics are read exclusively from environment variables
• Secrets are never logged, returned in tool outputs, or exposed in any way
• Works in read-only mode (price queries, quotes, balances) without any wallet configured

---

Quick start

# Run with npx (no install needed)
npx paean-dex-mcp

# Or install globally
npm install -g paean-dex-mcp
paean-dex-mcp

With a private key:

DEX_PRIVATE_KEY_BASE=0xabc...  \
DEX_PRIVATE_KEY_SOLANA=5Kb8... \
DEX_NETWORK=mainnet            \
npx paean-dex-mcp

Or with a mnemonic (same seed for both chains):

DEX_MNEMONIC="word1 word2 word3 ... word12" \
DEX_NETWORK=mainnet                         \
npx paean-dex-mcp

---

Wallet Configuration

The server supports two wallet modes. Private keys take precedence — if both a private key and a mnemonic are set for the same chain, the private key is used.

Option A: Private Keys (direct)

Set a separate private key per chain. Best for agents with dedicated hot-wallets.

DEX_PRIVATE_KEY_BASE=0xabc...    # Hex private key for Base (EVM)
DEX_PRIVATE_KEY_SOLANA=5Kb8...   # Base58 private key for Solana

Option B: Mnemonic (HD wallet)

Set a single BIP-39 mnemonic phrase to derive wallets for both chains. Compatible with Phantom, MetaMask, and other HD wallets.

DEX_MNEMONIC="abandon abandon abandon ... about"   # 12 or 24 words
DEX_HD_PATH_BASE="m/44'/60'/0'/0/0"                 # optional, default shown
DEX_HD_PATH_SOLANA="m/44'/501'/0'/0'"                # optional, default shown

Default derivation paths:

• Base (EVM): m/44'/60'/0'/0/0 — standard Ethereum/MetaMask path (first account)
• Solana: m/44'/501'/0'/0' — standard Phantom/Solflare path (first account)

To use a different account index, change the last number, e.g. m/44'/60'/0'/0/1 for the second Base account.

Mixing modes

You can use a private key for one chain and a mnemonic for the other:

DEX_PRIVATE_KEY_BASE=0xabc...                        # direct key for Base
DEX_MNEMONIC="abandon abandon abandon ... about"     # mnemonic for Solana

---

Environment Variables

Variable	Required	Default	Description
DEX_PRIVATE_KEY_BASE	For swaps†	—	Hex private key (0x…) for Base
DEX_PRIVATE_KEY_SOLANA	For swaps†	—	Base58 private key for Solana
DEX_MNEMONIC	For swaps†	—	BIP-39 mnemonic phrase (12 or 24 words)
DEX_HD_PATH_BASE	No	m/44'/60'/0'/0/0	HD derivation path for Base wallet
DEX_HD_PATH_SOLANA	No	m/44'/501'/0'/0'	HD derivation path for Solana wallet
DEX_NETWORK	No	mainnet	mainnet or testnet
DEX_DEFAULT_CHAIN	No	base	Default chain: base or solana
DEX_RPC_URL_BASE	No	https://mainnet.base.org	Custom Base RPC endpoint
DEX_RPC_URL_SOLANA	No	https://api.mainnet-beta.solana.com	Custom Solana RPC endpoint
DEX_SLIPPAGE_BPS	No	50	Default slippage in basis points (50 = 0.5%)

† At least one of DEX_PRIVATE_KEY_* or DEX_MNEMONIC is needed to execute swaps. Without any wallet, the server runs in read-only mode (price queries, quotes, balances).

Testnet defaults (DEX_NETWORK=testnet):

• Base Sepolia RPC: https://sepolia.base.org
• Solana devnet RPC: https://api.devnet.solana.com

---

Tools

list_common_tokens

List well-known tradeable tokens with addresses and decimals. Use this first to find token addresses for other tools.

{ "chain": "base" }

Returns tokens like USDC, WETH, USDT, AERO, BRETT with their contract addresses.

---

get_wallet_address

Get the configured wallet address(es). Safe to call — never reveals private keys.

{ "chain": "solana" }

---

get_token_balance

Get the balance of a token or native coin (ETH/SOL) for any wallet address.

{
  "chain": "base",
  "wallet_address": "0xYourAddress",
  "token_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
}

Omit token_address for native balance (ETH on Base, SOL on Solana).
Omit wallet_address to use the configured wallet.

---

get_token_price

Get the current USD price of any token using DEX pricing.

{
  "chain": "solana",
  "token_address": "JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN"
}

On Base: queries Uniswap v3 QuoterV2 via a USDC pair.
On Solana: queries Jupiter price API.

---

get_swap_quote

Get a swap quote with expected output, price impact, route, and minimum received. Always call this before execute_swap.

{
  "chain": "base",
  "input_token": "0x4200000000000000000000000000000000000006",
  "output_token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "input_amount": "0.1",
  "slippage_bps": 50
}

Returns:

{
  "chain": "base",
  "inputSymbol": "WETH",
  "outputSymbol": "USDC",
  "inputAmount": "0.1",
  "outputAmount": "315.42",
  "minOutputAmount": "313.84",
  "priceImpactPct": "0.0012",
  "slippageBps": 50,
  "route": [{ "protocol": "uniswap-v3-500", ... }]
}

---

execute_swap

Execute a token swap. Requires a private key to be configured.

{
  "chain": "solana",
  "input_token": "So11111111111111111111111111111111111111112",
  "output_token": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "input_amount": "0.5",
  "slippage_bps": 100,
  "deadline_minutes": 20
}

Returns:

{
  "success": true,
  "tx_hash": "5xBq...",
  "swapped": "0.5 SOL → 78.21 USDC",
  "explorer_url": "https://solscan.io/tx/5xBq..."
}

---

get_transaction_status

Look up a transaction by hash.

{
  "tx_hash": "0xabc...",
  "chain": "base"
}

---

Integration

paeanclaw

Add to paeanclaw.config.json:

{
  "mcpServers": {
    "dex": {
      "command": "npx",
      "args": ["-y", "paean-dex-mcp"],
      "env": {
        "DEX_PRIVATE_KEY_BASE": "${BASE_PRIVATE_KEY}",
        "DEX_PRIVATE_KEY_SOLANA": "${SOLANA_PRIVATE_KEY}",
        "DEX_NETWORK": "mainnet",
        "DEX_DEFAULT_CHAIN": "base"
      }
    }
  }
}

Or use a mnemonic to derive both wallets from one seed:

{
  "mcpServers": {
    "dex": {
      "command": "npx",
      "args": ["-y", "paean-dex-mcp"],
      "env": {
        "DEX_MNEMONIC": "${WALLET_MNEMONIC}",
        "DEX_NETWORK": "mainnet",
        "DEX_DEFAULT_CHAIN": "base"
      }
    }
  }
}

Tools are available as dex__get_swap_quote, dex__execute_swap, etc.

ai-paean-cli

Add to ~/.paean/mcp_config.json:

{
  "mcpServers": {
    "dex": {
      "command": "npx",
      "args": ["-y", "paean-dex-mcp"],
      "env": {
        "DEX_PRIVATE_KEY_BASE": "${BASE_PRIVATE_KEY}",
        "DEX_PRIVATE_KEY_SOLANA": "${SOLANA_PRIVATE_KEY}",
        "DEX_NETWORK": "mainnet"
      }
    }
  }
}

Load your keys from .env before starting:

source .env && paean
# or
npx dotenv-cli paean

Claude / Cursor MCP config

{
  "mcpServers": {
    "dex": {
      "command": "npx",
      "args": ["-y", "paean-dex-mcp"],
      "env": {
        "DEX_PRIVATE_KEY_BASE": "0xYourHexKey",
        "DEX_NETWORK": "mainnet"
      }
    }
  }
}

Or with a mnemonic:

{
  "mcpServers": {
    "dex": {
      "command": "npx",
      "args": ["-y", "paean-dex-mcp"],
      "env": {
        "DEX_MNEMONIC": "word1 word2 word3 ... word12",
        "DEX_NETWORK": "mainnet"
      }
    }
  }
}

---

Testing

Build first, then run the testnet integration test:

npm run build

# Test on Base Sepolia
DEX_PRIVATE_KEY_BASE=0x... node scripts/test-mcp.mjs --chain base

# Test on Solana devnet
DEX_PRIVATE_KEY_SOLANA=5Kb8... node scripts/test-mcp.mjs --chain solana

The test script covers all 7 tools with read-only checks (no key needed) and optionally executes a swap on testnet.

Testnet faucets:

• Base Sepolia: https://faucet.base.org
• Solana devnet: https://faucet.solana.com

---

Well-known token addresses

Base mainnet

Symbol	Address
WETH	0x4200000000000000000000000000000000000006
USDC	0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
USDT	0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2
DAI	0x50c5725949A6F0c72E6C4a641F24049A917DB0Cb
cbBTC	0xcbB7C0000aB88B473b1f5aFd9ef808440eed33Bf
AERO	0x940181a94A35A4569E4529A3CDfB74e38FD98631

Solana mainnet

Symbol	Mint
SOL (wrapped)	So11111111111111111111111111111111111111112
USDC	EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
USDT	Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB
JUP	JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN
BONK	DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263
WIF	EKpQGSJtjMFqKZ9KQanSqYXRcF8fBopzLHYxdM65zcjm

Use list_common_tokens to get the full curated list from within the MCP.

---

Security notes

• Never commit private keys or mnemonics to version control. Use environment variables or a secrets manager.
• The server runs with --no-server-sent-events; it uses stdio only, so it never opens a network port.
• execute_swap requires explicit confirmation of amount, tokens, and chain — it cannot be called without full parameters.
• get_swap_quote is always available to verify trade details before committing.
• When using a mnemonic, the derived private keys exist only in memory and are never persisted or exposed.

---

License

MIT — Paean AI