Paloma DEX MCP Server
Manages environment variables for secure configuration, particularly for storing private keys and contract addresses needed for trading operations
Enables trading on Ethereum Mainnet (Chain ID: 1) through Paloma DEX, allowing token purchases, sales, balance checks, and price queries
Supports trading operations on Optimism (Chain ID: 10) through Paloma DEX, with tools for buying/selling tokens and checking balances
Provides trading capabilities on Polygon (Chain ID: 137) through Paloma DEX, with support for cross-chain token exchanges
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Paloma DEX MCP Server get my PUSD balance on Arbitrum"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Related MCP server: EVM MCP Server
Features
Available Tools
Blockchain Data Access
get_account_info: Get account address and native token balances across all chainsget_pusd_balance: Get PUSD token balance on a specific chainget_chain_info: Get detailed information about a specific blockchainlist_supported_chains: List all supported chains with their configurationsget_address_balances: Get balances for any Ethereum address across all chains
ETF Trading Tools
get_etf_tokens: Get available ETF tokens on a specific chainget_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 denominationget_etf_balance: Get ETF token balance for a wallet addressbuy_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 mcpPADEXInstall dependencies using uv:
uv sync
Configuration
Set up environment variables:
cp .env.example .envConfigure your
.envfile 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_hereObtain 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.pyThe 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 frameworkmain.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 resourcesSecurity Considerations
⚠️ Important Security Notes:
Private keys are stored in environment variables
Ensure your
.envfile is never committed to version controlThe
.gitignorefile excludes.envby defaultConsider 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 fileAdding 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 dataContributing
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.
Available Tools
21 toolsadd_liquidityB
Add liquidity to a trading pool using the Trader contract.
Args:
chain_id: Chain ID (1, 10, 56, 100, 137, 8453, 42161)
token0_address: Address of first token
token1_address: Address of second token
token0_amount: Amount of first token in wei
token1_amount: Amount of second token in wei
Returns:
JSON string with liquidity addition transaction details.
Inputs: chain_id (required), token0_address (required), token1_address (required), token0_amount (required), +1 more.
approve_token_spendingA
Approve token spending for trading (two-step approval process).
Args:
chain_id: Chain ID (1, 10, 56, 100, 137, 8453, 42161)
token_address: Address of token to approve
spender_address: Address that will spend the tokens (typically Trader contract)
amount: Amount to approve in wei (defaults to unlimited)
Returns:
JSON string with approval transaction details.
Inputs: chain_id (required), token_address (required), spender_address (required), amount.
buy_etf_tokenA
Buy ETF tokens using input tokens (simulation only - no actual transaction).
Args:
chain_id: Chain ID (1, 10, 56, 100, 137, 8453, 42161)
etf_token_address: Address of the ETF token to buy
input_token_address: Address of token to spend (use 'native' for ETH/BNB/MATIC/xDAI)
input_amount: Amount of input token to spend (in token units, e.g. '1.5')
slippage: Slippage tolerance as percentage (default: 2.0)
Returns:
JSON string with transaction simulation details.
Inputs: chain_id (required), etf_token_address (required), input_token_address (required), input_amount (required), +1 more.
check_token_allowanceA
Check token allowance for a specific owner and spender.
Args:
chain_id: Chain ID (1, 10, 56, 100, 137, 8453, 42161)
token_address: Address of the token
owner_address: Address of the token owner
spender_address: Address of the spender (typically Trader contract)
Returns:
JSON string with allowance information.
Inputs: chain_id (required), token_address (required), owner_address (required), spender_address (required).
execute_token_swapB
Execute a token swap using the Trader contract.
Args:
chain_id: Chain ID (1, 10, 56, 100, 137, 8453, 42161)
from_token_address: Address of token to swap from
to_token_address: Address of token to swap to
amount_wei: Amount to swap in wei format
Returns:
JSON string with swap transaction details.
Inputs: chain_id (required), from_token_address (required), to_token_address (required), amount_wei (required).
get_account_infoB
Get account information including address and balances across all chains.
Returns:
JSON string with account address and native token balances on all supported chains.
Inputs: no named parameters.
get_address_balancesA
Get balances for a specific address across all chains (concurrent execution).
Args:
address: Ethereum address to check balances for
timeout_seconds: Timeout for the entire operation (default: 30 seconds)
Returns:
JSON string with balance information across all chains.
Inputs: address (required), timeout_seconds.
get_address_balance_single_chainA
Get balance for a specific address on a single chain (faster).
Args:
address: Ethereum address to check balances for
chain_id: Chain ID (1, 10, 56, 100, 137, 8453, 42161)
Returns:
JSON string with balance information for the specified chain.
Inputs: address (required), chain_id (required).
get_available_trading_tokensB
Get available tokens for trading on a specific chain.
Args:
chain_id: Chain ID (1, 10, 56, 100, 137, 8453, 42161)
Returns:
JSON string with available trading tokens and their information.
Inputs: chain_id (required).
get_chain_infoB
Get detailed information about a specific chain.
Args:
chain_id: Chain ID (1, 10, 56, 100, 137, 8453, 42161)
Returns:
JSON string with chain configuration and status.
Inputs: chain_id (required).
get_etf_balanceB
Get ETF token balance for a wallet address.
Args:
chain_id: Chain ID (1, 10, 56, 100, 137, 8453, 42161)
etf_token_address: Address of the ETF token
wallet_address: Wallet address to check (defaults to server wallet)
Returns:
JSON string with ETF token balance information.
Inputs: chain_id (required), etf_token_address (required), wallet_address.
get_etf_priceB
Get buy and sell prices for an ETF token.
Args:
chain_id: Chain ID (1, 10, 56, 100, 137, 8453, 42161)
etf_token_address: Address of the ETF token
Returns:
JSON string with buy and sell prices for the ETF token.
Inputs: chain_id (required), etf_token_address (required).
get_etf_price_by_paloma_denomB
Get ETF price by Paloma denomination.
Args:
paloma_denom: Paloma denomination (e.g., factory/paloma18xrvj2ffxygkmtqwf3tr6fjqk3w0dgg7m6ucwx/palomagold)
Returns:
JSON string with ETF price data.
Inputs: paloma_denom (required).
get_etf_price_by_symbolA
Get ETF price by token symbol from Paloma DEX.
Args:
symbol: ETF token symbol (e.g., PAGOLD, PABTC2X, PACBOA)
Returns:
JSON string with ETF price data.
Inputs: symbol (required).
get_etf_tokensB
Get available ETF tokens on a specific chain.
Args:
chain_id: Chain ID (1, 10, 56, 100, 137, 8453, 42161)
Returns:
JSON string with available ETF tokens and their information.
Inputs: chain_id (required).
get_pusd_balanceB
Get PUSD token balance on specified chain.
Args:
chain_id: Chain ID (1, 10, 56, 100, 137, 8453, 42161)
Returns:
JSON string with PUSD balance information.
Inputs: chain_id (required).
get_token_price_estimateA
Get real-time price estimate for token swap.
Args:
chain_id: Chain ID (1, 10, 56, 100, 137, 8453, 42161)
input_token_address: Address of token to trade from
output_token_address: Address of token to trade to
input_amount: Amount of input token in wei format
Returns:
JSON string with price estimate and trading information.
Inputs: chain_id (required), input_token_address (required), output_token_address (required), input_amount (required).
list_supported_chainsB
List all supported chains with their configurations.
Returns:
JSON string with all supported chain information.
Inputs: no named parameters.
remove_liquidityB
Remove liquidity from a trading pool using the Trader contract.
Args:
chain_id: Chain ID (1, 10, 56, 100, 137, 8453, 42161)
token0_address: Address of first token
token1_address: Address of second token
liquidity_amount: Amount of liquidity tokens to remove in wei
Returns:
JSON string with liquidity removal transaction details.
Inputs: chain_id (required), token0_address (required), token1_address (required), liquidity_amount (required).
sell_etf_tokenA
Sell ETF tokens back to base currency (simulation only - no actual transaction).
Args:
chain_id: Chain ID (1, 10, 56, 100, 137, 8453, 42161)
etf_token_address: Address of the ETF token to sell
etf_amount: Amount of ETF tokens to sell (in token units, e.g. '10.5')
Returns:
JSON string with transaction simulation details.
Inputs: chain_id (required), etf_token_address (required), etf_amount (required).
validate_trade_quoteA
Validate a trade against max spread and liquidity requirements.
Args:
chain_id: Chain ID (1, 10, 56, 100, 137, 8453, 42161)
input_token_address: Address of token to trade from
output_token_address: Address of token to trade to
input_amount: Amount of input token in wei format
Returns:
JSON string with trade validation results.
Inputs: chain_id (required), input_token_address (required), output_token_address (required), input_amount (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 21 tools
Most tools have distinct purposes with clear boundaries, such as add_liquidity vs. remove_liquidity or execute_token_swap vs. validate_trade_quote. However, some overlap exists in ETF price retrieval tools (get_etf_price, get_etf_price_by_paloma_denom, get_etf_price_by_symbol), which could cause confusion despite their different input parameters.
All tools follow a consistent verb_noun naming pattern using snake_case, such as add_liquidity, check_token_allowance, and get_account_info. The naming is predictable and readable throughout the set, with no deviations in style or convention.
With 21 tools, the count is borderline high for a DEX server, potentially overwhelming for agents. While the tools cover various aspects like liquidity, trading, balances, and ETFs, some consolidation might improve usability without losing functionality.
The tool set provides comprehensive coverage for a DEX domain, including liquidity management (add/remove), trading (swap, validate, price estimates), account/balance queries, ETF operations (buy/sell/price/balance), and chain/token information. No obvious gaps are present, supporting full workflows from approval to execution.
Maintenance
Related MCP Connectors
MCP server connecting AI agents to non-custodial staking data across 130+ networks.
HiveCapital MCP Server — autonomous investment layer for AI agents
Cross-asset market data, LLM gateway and ML forecasts for AI agents. USDC via x402 + MPP.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server enabling AI agents to interact with the Solana blockchain for DeFi operations like checking balances, transferring tokens, executing swaps, and fetching price data.21MIT
- AlicenseBqualityDmaintenanceA Model Context Protocol server that enables AI agents to interact with 30+ Ethereum-compatible blockchain networks, providing services like token transfers, contract interactions, and ENS resolution through a unified interface.2896 npm380MIT
- -licenseNot gradedqualityNot gradedmaintenanceComprehensive Model Context Protocol server that enables AI agents to interact with 30+ Ethereum-compatible blockchain networks, supporting token transfers, smart contract interactions, and ENS name resolution through a unified interface.1-
- AlicenseAqualityDmaintenanceA Model Context Protocol server that enables AI assistants and applications to interact with decentralized exchanges (DEXs), allowing users to get quotes for token swaps and execute swap transactions.313 npm1MIT