Paloma DEX MCP Server

A Model Context Protocol (MCP) server that enables AI agents to interact with Paloma DEX across 7 EVM chains. Built with FastMCP framework for modern MCP implementations.

Overview

This MCP server provides AI agents with tools to access blockchain data and prepare for decentralized trading operations on Paloma DEX. The server supports cross-chain functionality across Ethereum, Arbitrum, Optimism, Base, BSC, Polygon, and Gnosis chains.

Features

Available Tools

Blockchain Data Access

get_account_info: Get account address and native token balances across all chains
get_pusd_balance: Get PUSD token balance on a specific chain
get_chain_info: Get detailed information about a specific blockchain
list_supported_chains: List all supported chains with their configurations
get_address_balances: Get balances for any Ethereum address across all chains

ETF Trading Tools

get_etf_tokens: Get available ETF tokens on a specific chain
get_etf_price: Get buy and sell prices for an ETF token (by EVM address)
get_etf_price_by_symbol: Get ETF price by token symbol (recommended)
get_etf_price_by_paloma_denom: Get ETF price by Paloma denomination
get_etf_balance: Get ETF token balance for a wallet address
buy_etf_token: Buy ETF tokens using input tokens (simulation)
sell_etf_token: Sell ETF tokens back to base currency (simulation)

Chain Support

Supports all 7 EVM chains used by Paloma DEX:

Ethereum Mainnet (Chain ID: 1)
Arbitrum One (Chain ID: 42161)
Optimism (Chain ID: 10)
Base (Chain ID: 8453)
BNB Smart Chain (Chain ID: 56)
Polygon (Chain ID: 137)
Gnosis (Chain ID: 100)

Key Capabilities

Multi-Chain Data Access: Query balances and chain information across all 7 supported chains
ETF Trading Support: Complete ETF token ecosystem integration with Paloma DEX API
FastMCP Framework: Built with modern MCP implementation for better performance
Web3 Integration: Direct blockchain interaction via Web3 clients
Transaction Simulation: Safe simulation of trading operations before execution
Error Handling: Comprehensive error management and validation
Address Validation: Ethereum address format validation
Contract Integration: Integration with PUSD and ETF connector contracts

Installation

Clone the repository:

git clone https://github.com/Cieloc/mcpPADEX.git
cd mcpPADEX

Install dependencies using uv:
```
uv sync
```

Configuration

Set up environment variables:
```
cp .env.example .env
```

Configure your .env file with the following required variables:

# REQUIRED: Your private key for transaction signing
# WARNING: Keep this secure and never commit to version control
PRIVATE_KEY=your_private_key_here

# Contract addresses for each chain (obtain from Paloma DEX)
PUSD_TOKEN_ETH=
PUSD_CONNECTOR_ETH=
ETF_CONNECTOR_ETH=
# ... (repeat for all chains)

# Optional: Moralis API key for enhanced features
MORALIS_SERVICE_API_KEY=your_moralis_api_key_here

Obtain contract addresses from Paloma DEX documentation or team for:
- PUSD token addresses
- PUSD connector addresses
- ETF connector addresses

Usage

Running the Server

uv run padex.py

The server will start and listen for MCP protocol messages via stdin/stdout.

Tool Examples

Get Account Information

{
  "tool": "get_account_info",
  "arguments": {}
}

Get PUSD Balance

{
  "tool": "get_pusd_balance",
  "arguments": {
    "chain_id": "1"
  }
}

Get Chain Information

{
  "tool": "get_chain_info",
  "arguments": {
    "chain_id": "42161"
  }
}

List All Supported Chains

{
  "tool": "list_supported_chains",
  "arguments": {}
}

Get Address Balances

{
  "tool": "get_address_balances",
  "arguments": {
    "address": "0x742d35Cc6648C4532b6C4EC000e40fd94aea4966"
  }
}

Get Available ETF Tokens

{
  "tool": "get_etf_tokens",
  "arguments": {
    "chain_id": "1"
  }
}

Get ETF Token Price (by EVM address)

{
  "tool": "get_etf_price",
  "arguments": {
    "chain_id": "1",
    "etf_token_address": "0x1234567890123456789012345678901234567890"
  }
}

Get ETF Price by Symbol (Recommended)

{
  "tool": "get_etf_price_by_symbol",
  "arguments": {
    "symbol": "PAGOLD"
  }
}

Get ETF Price by Paloma Denomination

{
  "tool": "get_etf_price_by_paloma_denom",
  "arguments": {
    "paloma_denom": "factory/paloma18xrvj2ffxygkmtqwf3tr6fjqk3w0dgg7m6ucwx/palomagold"
  }
}

Get ETF Token Balance

{
  "tool": "get_etf_balance",
  "arguments": {
    "chain_id": "1",
    "etf_token_address": "0x1234567890123456789012345678901234567890",
    "wallet_address": "0x742d35Cc6648C4532b6C4EC000e40fd94aea4966"
  }
}

Buy ETF Tokens (Simulation)

{
  "tool": "buy_etf_token",
  "arguments": {
    "chain_id": "1",
    "etf_token_address": "0x1234567890123456789012345678901234567890",
    "input_token_address": "native",
    "input_amount": "1.0",
    "slippage": 2.0
  }
}

Sell ETF Tokens (Simulation)

{
  "tool": "sell_etf_token",
  "arguments": {
    "chain_id": "1",
    "etf_token_address": "0x1234567890123456789012345678901234567890",
    "etf_amount": "10.0"
  }
}

Architecture

Core Components

padex.py: Main MCP server implementation using FastMCP framework
main.py: Simple entry point (Hello World)
FastMCP Framework: Modern MCP server implementation with lifecycle management
Chain Configuration: Complete configuration for all 7 supported chains
Web3 Clients: Individual Web3 connections for each blockchain

Architecture Pattern

The server uses FastMCP's lifespan context management:

@asynccontextmanager
async def paloma_dex_lifespan(server: FastMCP) -> AsyncIterator[PalomaDEXContext]:
    # Initialize Web3 clients and resources
    yield context
    # Cleanup resources

Security Considerations

⚠️ Important Security Notes:

Private keys are stored in environment variables
Ensure your .env file is never committed to version control
The .gitignore file excludes .env by default
Consider using more secure key management for production use

Dependencies

mcp[cli]: Model Context Protocol with FastMCP framework
web3: Ethereum blockchain interaction
eth-account: Private key and transaction signing
eth-abi: ABI encoding for contract calls
httpx: HTTP client for API interactions
python-dotenv: Environment variable management

API Integrations

The server integrates with:

Blockchain RPC Endpoints: Direct connection to each supported chain
ERC-20 Token Contracts: For PUSD and ETF token balance queries
Paloma DEX API: Live integration for ETF token data and pricing
ETF Connector Contracts: Smart contracts for ETF trading operations

Development

Project Structure

mcpPADEX/
├── padex.py                      # Main FastMCP server implementation
├── padex_old.py                  # Previous implementation (backup)
├── main.py                       # Simple entry point
├── pyproject.toml                # Project dependencies
├── .env                          # Environment variables (not committed)
├── .gitignore                    # Git ignore rules
├── MCP_DOCUMENTATION.md          # MCP protocol reference
├── MCP_PYTHON_SDK_REFERENCE.md   # FastMCP SDK reference
├── mcp-llms-full-reference.txt   # Complete MCP reference
└── README.md                     # This file

Adding New Features

The server uses FastMCP decorators for easy extension:

@mcp.tool()
async def new_tool(ctx: Context, param: str) -> str:
    """Tool description"""
    # Implementation
    return result

@mcp.resource("resource://pattern/{id}")
async def new_resource(id: str) -> str:
    """Resource description"""
    # Implementation
    return data

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is open source. Please check the license file for details.

Disclaimer

This software is provided "as is" without warranty. Trading cryptocurrencies involves risk of loss. Use at your own risk and ensure you understand the implications of automated trading before deployment.

Support

For questions about Paloma DEX integration, consult the Paloma DEX documentation or reach out to the Paloma team.

For MCP-related questions, see the Model Context Protocol documentation.