{"id":30029358,"url":"https://github.com/volumefi/mcppadex","last_synced_at":"2026-05-06T15:42:23.845Z","repository":{"id":300811793,"uuid":"1005764835","full_name":"VolumeFi/mcpPADEX","owner":"VolumeFi","description":"MCP Server for PalomaDex at Palomadex.com","archived":false,"fork":false,"pushed_at":"2025-06-23T18:00:29.000Z","size":25,"stargazers_count":0,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-06-23T18:47:07.195Z","etag":null,"topics":["agentic-ai","agentic-workflow","agents","ai","mcp","mcp-server","server"],"latest_commit_sha":null,"homepage":"https://palomadex.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/VolumeFi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-20T19:22:14.000Z","updated_at":"2025-06-23T18:00:33.000Z","dependencies_parsed_at":"2025-06-23T18:47:09.639Z","dependency_job_id":"028f8120-fdec-4804-a556-54bc997bc7c7","html_url":"https://github.com/VolumeFi/mcpPADEX","commit_stats":null,"previous_names":["volumefi/mcppadex"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/VolumeFi/mcpPADEX","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VolumeFi%2FmcpPADEX","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VolumeFi%2FmcpPADEX/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VolumeFi%2FmcpPADEX/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VolumeFi%2FmcpPADEX/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/VolumeFi","download_url":"https://codeload.github.com/VolumeFi/mcpPADEX/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VolumeFi%2FmcpPADEX/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269118397,"owners_count":24362994,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-06T02:00:09.910Z","response_time":99,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-ai","agentic-workflow","agents","ai","mcp","mcp-server","server"],"created_at":"2025-08-06T17:03:14.324Z","updated_at":"2026-05-06T15:42:23.812Z","avatar_url":"https://github.com/VolumeFi.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Paloma DEX MCP Server\n\nA 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.\n\n## Overview\n\nThis 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.\n\n## Features\n\n### Available Tools\n\n#### Blockchain Data Access\n- **`get_account_info`**: Get account address and native token balances across all chains\n- **`get_pusd_balance`**: Get PUSD token balance on a specific chain\n- **`get_chain_info`**: Get detailed information about a specific blockchain\n- **`list_supported_chains`**: List all supported chains with their configurations\n- **`get_address_balances`**: Get balances for any Ethereum address across all chains\n\n#### ETF Trading Tools\n- **`get_etf_tokens`**: Get available ETF tokens on a specific chain\n- **`get_etf_price`**: Get buy and sell prices for an ETF token (by EVM address)\n- **`get_etf_price_by_symbol`**: Get ETF price by token symbol (recommended)\n- **`get_etf_price_by_paloma_denom`**: Get ETF price by Paloma denomination\n- **`get_etf_balance`**: Get ETF token balance for a wallet address\n- **`buy_etf_token`**: Buy ETF tokens using input tokens (simulation)\n- **`sell_etf_token`**: Sell ETF tokens back to base currency (simulation)\n\n### Chain Support\n\nSupports all 7 EVM chains used by Paloma DEX:\n- **Ethereum Mainnet** (Chain ID: 1)\n- **Arbitrum One** (Chain ID: 42161)\n- **Optimism** (Chain ID: 10)\n- **Base** (Chain ID: 8453)\n- **BNB Smart Chain** (Chain ID: 56)\n- **Polygon** (Chain ID: 137)\n- **Gnosis** (Chain ID: 100)\n\n### Key Capabilities\n\n- **Multi-Chain Data Access**: Query balances and chain information across all 7 supported chains\n- **ETF Trading Support**: Complete ETF token ecosystem integration with Paloma DEX API\n- **FastMCP Framework**: Built with modern MCP implementation for better performance\n- **Web3 Integration**: Direct blockchain interaction via Web3 clients\n- **Transaction Simulation**: Safe simulation of trading operations before execution\n- **Error Handling**: Comprehensive error management and validation\n- **Address Validation**: Ethereum address format validation\n- **Contract Integration**: Integration with PUSD and ETF connector contracts\n\n## Installation\n\n1. **Clone the repository**:\n   ```bash\n   git clone https://github.com/Cieloc/mcpPADEX.git\n   cd mcpPADEX\n   ```\n\n2. **Install dependencies** using [uv](https://docs.astral.sh/uv/):\n   ```bash\n   uv sync\n   ```\n\n## Configuration\n\n1. **Set up environment variables**:\n   ```bash\n   cp .env.example .env\n   ```\n\n2. **Configure your `.env` file** with the following required variables:\n\n   ```bash\n   # REQUIRED: Your private key for transaction signing\n   # WARNING: Keep this secure and never commit to version control\n   PRIVATE_KEY=your_private_key_here\n\n   # Contract addresses for each chain (obtain from Paloma DEX)\n   PUSD_TOKEN_ETH=\n   PUSD_CONNECTOR_ETH=\n   ETF_CONNECTOR_ETH=\n   # ... (repeat for all chains)\n\n   # Optional: Moralis API key for enhanced features\n   MORALIS_SERVICE_API_KEY=your_moralis_api_key_here\n   ```\n\n3. **Obtain contract addresses** from Paloma DEX documentation or team for:\n   - PUSD token addresses\n   - PUSD connector addresses  \n   - ETF connector addresses\n\n## Usage\n\n### Running the Server\n\n```bash\nuv run padex.py\n```\n\nThe server will start and listen for MCP protocol messages via stdin/stdout.\n\n### Tool Examples\n\n#### Get Account Information\n```json\n{\n  \"tool\": \"get_account_info\",\n  \"arguments\": {}\n}\n```\n\n#### Get PUSD Balance\n```json\n{\n  \"tool\": \"get_pusd_balance\",\n  \"arguments\": {\n    \"chain_id\": \"1\"\n  }\n}\n```\n\n#### Get Chain Information\n```json\n{\n  \"tool\": \"get_chain_info\",\n  \"arguments\": {\n    \"chain_id\": \"42161\"\n  }\n}\n```\n\n#### List All Supported Chains\n```json\n{\n  \"tool\": \"list_supported_chains\",\n  \"arguments\": {}\n}\n```\n\n#### Get Address Balances\n```json\n{\n  \"tool\": \"get_address_balances\",\n  \"arguments\": {\n    \"address\": \"0x742d35Cc6648C4532b6C4EC000e40fd94aea4966\"\n  }\n}\n```\n\n#### Get Available ETF Tokens\n```json\n{\n  \"tool\": \"get_etf_tokens\",\n  \"arguments\": {\n    \"chain_id\": \"1\"\n  }\n}\n```\n\n#### Get ETF Token Price (by EVM address)\n```json\n{\n  \"tool\": \"get_etf_price\",\n  \"arguments\": {\n    \"chain_id\": \"1\",\n    \"etf_token_address\": \"0x1234567890123456789012345678901234567890\"\n  }\n}\n```\n\n#### Get ETF Price by Symbol (Recommended)\n```json\n{\n  \"tool\": \"get_etf_price_by_symbol\",\n  \"arguments\": {\n    \"symbol\": \"PAGOLD\"\n  }\n}\n```\n\n#### Get ETF Price by Paloma Denomination\n```json\n{\n  \"tool\": \"get_etf_price_by_paloma_denom\",\n  \"arguments\": {\n    \"paloma_denom\": \"factory/paloma18xrvj2ffxygkmtqwf3tr6fjqk3w0dgg7m6ucwx/palomagold\"\n  }\n}\n```\n\n#### Get ETF Token Balance\n```json\n{\n  \"tool\": \"get_etf_balance\",\n  \"arguments\": {\n    \"chain_id\": \"1\",\n    \"etf_token_address\": \"0x1234567890123456789012345678901234567890\",\n    \"wallet_address\": \"0x742d35Cc6648C4532b6C4EC000e40fd94aea4966\"\n  }\n}\n```\n\n#### Buy ETF Tokens (Simulation)\n```json\n{\n  \"tool\": \"buy_etf_token\",\n  \"arguments\": {\n    \"chain_id\": \"1\",\n    \"etf_token_address\": \"0x1234567890123456789012345678901234567890\",\n    \"input_token_address\": \"native\",\n    \"input_amount\": \"1.0\",\n    \"slippage\": 2.0\n  }\n}\n```\n\n#### Sell ETF Tokens (Simulation)\n```json\n{\n  \"tool\": \"sell_etf_token\",\n  \"arguments\": {\n    \"chain_id\": \"1\",\n    \"etf_token_address\": \"0x1234567890123456789012345678901234567890\",\n    \"etf_amount\": \"10.0\"\n  }\n}\n```\n\n## Architecture\n\n### Core Components\n\n- **`padex.py`**: Main MCP server implementation using FastMCP framework\n- **`main.py`**: Simple entry point (Hello World)\n- **FastMCP Framework**: Modern MCP server implementation with lifecycle management\n- **Chain Configuration**: Complete configuration for all 7 supported chains\n- **Web3 Clients**: Individual Web3 connections for each blockchain\n\n### Architecture Pattern\n\nThe server uses FastMCP's lifespan context management:\n\n```python\n@asynccontextmanager\nasync def paloma_dex_lifespan(server: FastMCP) -\u003e AsyncIterator[PalomaDEXContext]:\n    # Initialize Web3 clients and resources\n    yield context\n    # Cleanup resources\n```\n\n### Security Considerations\n\n⚠️ **Important Security Notes**:\n- Private keys are stored in environment variables\n- Ensure your `.env` file is never committed to version control\n- The `.gitignore` file excludes `.env` by default\n- Consider using more secure key management for production use\n\n### Dependencies\n\n- **mcp[cli]**: Model Context Protocol with FastMCP framework\n- **web3**: Ethereum blockchain interaction\n- **eth-account**: Private key and transaction signing\n- **eth-abi**: ABI encoding for contract calls\n- **httpx**: HTTP client for API interactions\n- **python-dotenv**: Environment variable management\n\n## API Integrations\n\nThe server integrates with:\n- **Blockchain RPC Endpoints**: Direct connection to each supported chain\n- **ERC-20 Token Contracts**: For PUSD and ETF token balance queries\n- **Paloma DEX API**: Live integration for ETF token data and pricing\n- **ETF Connector Contracts**: Smart contracts for ETF trading operations\n\n## Development\n\n### Project Structure\n```\nmcpPADEX/\n├── padex.py                      # Main FastMCP server implementation\n├── padex_old.py                  # Previous implementation (backup)\n├── main.py                       # Simple entry point\n├── pyproject.toml                # Project dependencies\n├── .env                          # Environment variables (not committed)\n├── .gitignore                    # Git ignore rules\n├── MCP_DOCUMENTATION.md          # MCP protocol reference\n├── MCP_PYTHON_SDK_REFERENCE.md   # FastMCP SDK reference\n├── mcp-llms-full-reference.txt   # Complete MCP reference\n└── README.md                     # This file\n```\n\n### Adding New Features\n\nThe server uses FastMCP decorators for easy extension:\n\n```python\n@mcp.tool()\nasync def new_tool(ctx: Context, param: str) -\u003e str:\n    \"\"\"Tool description\"\"\"\n    # Implementation\n    return result\n\n@mcp.resource(\"resource://pattern/{id}\")\nasync def new_resource(id: str) -\u003e str:\n    \"\"\"Resource description\"\"\"\n    # Implementation\n    return data\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nThis project is open source. Please check the license file for details.\n\n## Disclaimer\n\nThis 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.\n\n## Support\n\nFor questions about Paloma DEX integration, consult the [Paloma DEX documentation](https://docs.palomachain.com/) or reach out to the Paloma team.\n\nFor MCP-related questions, see the [Model Context Protocol documentation](https://modelcontextprotocol.io/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvolumefi%2Fmcppadex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvolumefi%2Fmcppadex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvolumefi%2Fmcppadex/lists"}