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