# 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](https://modelcontextprotocol.io) 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

```bash
# 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:

```bash
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):

```bash
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.

```bash
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.

```bash
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:

```bash
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.

```json
{ "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.

```json
{ "chain": "solana" }
```

---

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

```json
{
  "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.

```json
{
  "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`.

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

Returns:

```json
{
  "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.

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

Returns:

```json
{
  "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.

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

---

## Integration

### paeanclaw

Add to `paeanclaw.config.json`:

```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:

```json
{
  "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`:

```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:

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

### Claude / Cursor MCP config

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

Or with a mnemonic:

```json
{
  "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:

```bash
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](https://paean.ai)