🤖💰 Universal Crypto MCP

██╗ ██╗███╗ ██╗██╗██╗ ██╗███████╗██████╗ ███████╗ █████╗ ██╗
██║ ██║████╗ ██║██║██║ ██║██╔════╝██╔══██╗██╔════╝██╔══██╗██║
██║ ██║██╔██╗ ██║██║██║ ██║█████╗ ██████╔╝███████╗███████║██║
██║ ██║██║╚██╗██║██║╚██╗ ██╔╝██╔══╝ ██╔══██╗╚════██║██╔══██║██║
╚██████╔╝██║ ╚████║██║ ╚████╔╝ ███████╗██║ ██║███████║██║ ██║███████╗ ╚═════╝ ╚═╝ ╚═══╝╚═╝ ╚═══╝ ╚══════╝╚═╝ ╚═╝╚══════╝╚═╝ ╚═╝╚══════╝ ██████╗██████╗ ██╗ ██╗██████╗ ████████╗ ██████╗
██╔════╝██╔══██╗╚██╗ ██╔╝██╔══██╗╚══██╔══╝██╔═══██╗
██║ ██████╔╝ ╚████╔╝ ██████╔╝ ██║ ██║ ██║
██║ ██╔══██╗ ╚██╔╝ ██╔═══╝ ██║ ██║ ██║
╚██████╗██║ ██║ ██║ ██║ ██║ ╚██████╔╝
╚═════╝╚═╝ ╚═╝ ╚═╝ ╚═╝ ╚═╝ ╚═════╝
███╗ ███╗ ██████╗██████╗
████╗ ████║██╔════╝██╔══██╗
██╔████╔██║██║ ██████╔╝
██║╚██╔╝██║██║ ██╔═══╝
██║ ╚═╝ ██║╚██████╗██║
╚═╝ ╚═╝ ╚═════╝╚═╝

npx @nirholas/universal-crypto-mcp

✨ What’s New: AI Service Marketplace

Monetize your AI services & discover the best APIs! 💸

The AI Service Marketplace is a complete ecosystem for AI service discovery, monetization, and reputation management:

• 🏪 Register your AI service - Instant monetization with pay-per-use or subscriptions
• 🔍 AI agents discover services - Automatic discovery by category, price, and rating
• ⭐ On-chain reputation - Build trust with verified ratings and reviews
• 💳 Flexible pricing - Pay-per-use, subscriptions, free tiers
• 📊 Analytics dashboard - Track usage, revenue, and performance
• 🔒 Secure payments - Escrow, dispute resolution, automatic refunds

Learn more → | View Tutorial →

x402 Payment Protocol

AI agents can now pay for things on the internet! 💸

User: "Get premium weather data for Tokyo"

Claude: 🔍 Checking x402 balance... $45.23 USDs
        💳 Paying $0.01 for premium API access...
        ✅ Payment confirmed! Here's your detailed forecast:
        
        🌤️ Tokyo Weather (7-day premium forecast)...

AI agents can now:

• 💸 Pay for premium APIs automatically
• 🏪 Sell their own services to other agents
• 🔄 Trade with other AI agents peer-to-peer
• ⛓️ Work across EVM + Solana chains

⭐ If you find this useful, please star the repo! It helps others discover this project.

---

A Universal Model Context Protocol server for all EVM-compatible networks + Solana.

Enable AI agents (Claude, ChatGPT, Cursor) to interact with any EVM blockchain through natural language.

🆚 Why Universal Crypto MCP?

---

📦 Package Structure

The most comprehensive crypto MCP monorepo with 10+ integrated packages from the best MIT-licensed projects:

packages/
├── core/               # Shared types, utilities, configuration
├── trading/            # CEX exchange integrations
│   ├── binance/        # Binance spot & futures
│   ├── binance-us/     # Binance US
│   └── bybit/          # Bybit exchange (ethancod1ng) ⭐ NEW
├── market-data/        # Prices, news, analytics  
│   ├── prices/         # CoinGecko, DexPaprika, CoinMarketCap
│   ├── news/           # CryptoPanic, aggregated news
│   ├── analytics/      # Whale tracking, Fear/Greed, Dune
│   ├── predictions/    # AI price predictions
│   ├── crypto-indicators/  # Technical analysis (Kukapay) ⭐ NEW
│   ├── crypto-sentiment/   # Sentiment analysis (Kukapay) ⭐ NEW
│   ├── crypto-feargreed/   # Fear & Greed Index (Kukapay) ⭐ NEW
│   ├── cryptopanic/        # News aggregation (Kukapay)
│   └── coinmarketcap/      # CMC API (Shinzo Labs) ⭐ NEW
├── defi/               # On-chain DeFi tools (60+ networks!)
│   ├── protocols/      # EVM MCP Server (360⭐), Sperax, DEX
│   │   ├── algorand/   # Algorand tools (GoPlausible) ⭐ NEW
│   │   └── bsc-ops/    # BSC operations (TermiX) ⭐ NEW
│   ├── chain-tools/    # BNB Chain, Onchain MCP
│   └── agents/         # Autonomous DeFi agents
├── wallets/            # Wallet management
│   ├── evm/            # Ethereum & EVM wallets
│   └── solana/         # Solana wallets
├── payments/           # Payment infrastructure
│   └── x402/           # x402 protocol, USDC transfers
├── automation/         # Bots & automation
│   ├── social/         # XActions Twitter automation
│   ├── sweep/          # Dust sweeping
│   └── volume/         # Volume tools
└── generators/         # Meta-tools for building MCP servers
    ├── abi-to-mcp/     # Convert ABIs to MCP tools
    ├── repo-to-mcp/    # GitHub repos → MCP servers
    ├── doc-extractor/  # Extract docs for LLMs
    ├── registry/       # Lyra tool registry
    └── discovery/      # Tool discovery & search

📖 View Package Documentation →

Integrated Community MCP Servers

This repo consolidates the best MIT-licensed crypto MCP projects with proper attribution:

All integrated projects maintain their original MIT licenses with full attribution.
See CONTRIBUTORS.md for detailed attribution and our modifications.

---

Supported Networks

EVM Chains

• Ethereum, BNB Smart Chain (BSC), Polygon, Arbitrum, Base, Optimism
• Avalanche, Fantom, zkSync Era, Linea, Scroll, Blast, Mode, Mantle
• opBNB + All testnets

Multi-Chain (NEW)

• Cosmos/IBC - ATOM, OSMO, JUNO, INJ, and more
• Near Protocol - NEAR native + contracts
• Sui - SUI with Move support
• Aptos - APT with Move support
• Bitcoin, Litecoin, Solana, TON, XRP, THORChain

Features

• 🔄 Swap/DEX - Token swaps via 1inch, 0x, ParaSwap
• 🌉 Bridge - Cross-chain transfers via LayerZero, Stargate, Wormhole
• ⛽ Gas - Gas prices across chains, EIP-1559 suggestions
• 📦 Multicall - Batch read/write operations
• 📊 Events/Logs - Query historical events, decode logs
• 🔒 Security - Rug pull detection, honeypot check, GoPlus token/address security, dApp phishing detection
• 💰 Staking - Liquid staking (Lido), LP farming
• ✍️ Signatures - Sign messages, verify signatures, EIP-712
• 🏦 Lending - Aave/Compound positions, borrow rates
• 📈 Price Feeds - Historical prices, TWAP, oracle aggregation
• 📁 Portfolio - Track holdings across chains
• 🏛️ Governance - Snapshot votes, on-chain proposals
• 🚀 Deployment - Deploy contracts, CREATE2, upgradeable proxies, verification
• 🛡️ MEV Protection - Flashbots Protect, private transactions, bundle simulation
• 🆔 ENS/Domains - Register, transfer, renew, set records, subdomains
• 📊 Market Data - CoinGecko & CoinStats prices, OHLCV, trending, categories, exchanges
• 🌐 DeFi Analytics - DefiLlama TVL, yields, fees, bridges, stablecoins, protocol data
• 💬 Social Sentiment - LunarCrush social metrics, influencers, trending topics
• 📈 DEX Analytics - DexPaprika & GeckoTerminal pools, trades, OHLCV, trending tokens
• 🔮 Predictions - Polymarket prediction markets, crypto forecasts
• 📉 Technical Indicators - 50+ indicators (RSI, MACD, Bollinger Bands, etc.)
• 🔔 Alerts - Price alerts, whale movement alerts, gas alerts (NEW)
• 📡 WebSockets - Real-time price streams, trade feeds, mempool monitoring (NEW)
• 🐋 Wallet Analytics - Whale tracking, wallet scoring, behavior analysis (NEW)
• 🌐 Multi-Chain - Cosmos, Near, Sui, Aptos native support (NEW)
• 💰 x402 Payments - AI agents can pay for premium APIs automatically (NEW)

---

💰 x402 Payment Protocol (NEW!)

Give Claude Money! AI agents can now make and receive cryptocurrency payments.

What is x402?

x402 implements HTTP 402 Payment Required, enabling AI agents to:

• 💸 Pay for APIs - Automatically pay for premium API access
• 🤖 Autonomous Payments - No human approval needed
• 🏦 Hold funds - Agents have their own crypto wallets
• 📈 Earn yield - Payments use USDs stablecoin (~5% APY auto-yield)

Quick Setup

# Add to your environment
export X402_PRIVATE_KEY=0x...  # Your EVM private key
export X402_CHAIN=arbitrum      # Default chain (or base, ethereum, polygon)

x402 Tools (14 Total)

Supported Networks

Example

User: "Get premium weather data for Tokyo"
Agent: [calls x402_pay_request to weather API]
       [automatically pays $0.01 in USDs]
       "Here's the detailed forecast..."

x402 Architecture

┌─────────┐      ┌───────────┐      ┌───────────┐
│ Claude  │─────▶│ MCP Server│─────▶│ Paid API  │
│  (AI)   │      │  (x402)   │      │   (402)   │
└─────────┘      └───────────┘      └───────────┘
     │                │                   │
     │  "Get data"    │  HTTP + Payment   │
     │                │                   │
     └────────────────┴───────────────────┘

📖 Full Documentation:

• x402 README - Overview and quick start
• Quickstart Guide - 5-minute setup
• MCP Tools Reference - All 14 tools explained
• Architecture - Technical deep dive
• Examples - Real-world use cases
• Security Guide - Best practices

---

Quick Start

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "universal-crypto-mcp": {
      "command": "npx",
      "args": ["-y", "@nirholas/universal-crypto-mcp@latest"],
      "env": {
        "PRIVATE_KEY": "your_private_key_here (optional)"
      }
    }
  }
}

Cursor

Add to your MCP settings:

{
  "mcpServers": {
    "universal-crypto-mcp": {
      "command": "npx",
      "args": ["-y", "@nirholas/universal-crypto-mcp@latest"],
      "env": {
        "PRIVATE_KEY": "your_private_key_here (optional)"
      }
    }
  }
}

ChatGPT Developer Mode

1. Enable Developer Mode in ChatGPT settings
2. Start the HTTP server:

   npx @nirholas/universal-crypto-mcp@latest --http
   

3. In ChatGPT Settings → Apps, click Create app
4. Enter your server URL: http://localhost:3001/mcp
5. Select the app in conversations via Developer mode menu

For detailed setup instructions, see ChatGPT Setup Guide.

Server Modes

---

---

🧪 Testing

We use Vitest as our testing framework with comprehensive test coverage.

Running Tests

# Run all unit tests
npm test

# Run tests in watch mode (re-runs on file changes)
npm run test:watch

# Run tests with coverage report
npm run test:coverage

# Run E2E tests (requires network access)
npm run test:e2e

# Run E2E tests in watch mode
npm run test:e2e:watch

# Open interactive test UI
npm run test:ui

MCP Inspector

Test your MCP tools interactively using the official MCP Inspector:

npm run test:inspector

This opens a browser-based UI where you can:

• Browse all available tools and prompts
• Test tool execution with custom parameters
• View tool responses and debug issues
• Validate your MCP server implementation

Test Structure

tests/
├── setup.ts              # Global test setup
├── e2e/                  # End-to-end tests
│   ├── evm-tools.e2e.test.ts
│   └── market-data.e2e.test.ts
├── integration/          # Integration tests
│   ├── evm-tools.test.ts
│   └── multichain.test.ts
└── mocks/                # Test mocks and fixtures

src/
├── evm/
│   ├── chains.test.ts    # Unit tests alongside source
│   └── modules/
│       └── */tools.test.ts
└── utils/
    ├── errors.test.ts
    ├── helper.test.ts
    └── validation.test.ts

---

Local Development

# Clone
git clone https://github.com/nirholas/universal-crypto-mcp
cd universal-crypto-mcp

# Install
npm install

# Run dev server (stdio - Claude)
npm run dev

# Run dev server (HTTP - ChatGPT)
npm run dev:http

# Run dev server (SSE - legacy)
npm run dev:sse

---

🧪 Testing

Running Tests

# Run all tests
npm test

# Run unit tests only
npm run test:unit

# Run integration tests
npm run test:integration

# Run E2E tests (requires network access)
npm run test:e2e

# Run tests with coverage report
npm run test:coverage

# Run tests in watch mode (development)
npm run test:watch

Test Structure

E2E Tests

End-to-end tests verify the complete tool execution flow:

• EVM Tools - Block, balance, token operations across chains
• DeFi Tools - Protocol TVL, yields, stablecoins via DefiLlama
• Market Data - CoinGecko, Fear & Greed index
• Multichain - Same operations across different networks
• Error Recovery - Error handling, invalid inputs, edge cases

Custom Test Utilities

The project includes custom Vitest matchers for MCP responses:

// In your test file
import "../utils/assertions"

expect(result).toBeSuccessfulToolResponse()
expect(result).toHaveJsonProperty("balance")
expect(result).toContainValidAddress()
expect(result).toContainToolError(/invalid/i)

Test Fixtures

Reusable test data in tests/utils/fixtures.ts:

import {
  ETH_MAINNET_ADDRESSES,
  MOCK_TOKEN_DATA,
  generateRandomAddress
} from "../utils/fixtures"

For detailed testing documentation, see tests/README.md.

---

⚙️ Environment Variables

Configure optional API keys for enhanced features. Create a .env file:

# Required for write operations (swaps, transfers, etc.)
PRIVATE_KEY=your_private_key_here

# Market Data (optional - has free tier)
COINGECKO_API_KEY=your_key        # https://coingecko.com/api
COINSTATS_API_KEY=your_key        # https://coinstats.app

# Social Sentiment (optional)
LUNARCRUSH_API_KEY=your_key       # https://lunarcrush.com/developers

# News (optional)
CRYPTOPANIC_API_KEY=your_key      # https://cryptopanic.com/developers

# Cross-chain Swaps (optional)
RUBIC_API_KEY=your_key            # https://rubic.exchange

# Custom RPC endpoints (optional - uses public RPCs by default)
ETHEREUM_RPC_URL=https://mainnet.infura.io/v3/YOUR_KEY
ARBITRUM_RPC_URL=https://arb1.arbitrum.io/rpc
BASE_RPC_URL=https://mainnet.base.org

What Works Without API Keys

---

Documentation

https://mcp.giving

---

� Documentation & Examples

📖 Documentation

Comprehensive guides and API references:

• Getting Started

  • Installation Guide
  • Configuration
  • Your First MCP Tool
  • Deployment Guide

• Package Documentation

  • Core Package
  • Trading
  • Market Data
  • Wallets
  • DeFi
  • Payments (x402)

• x402 Deploy Documentation

  • Overview
  • Quick Start
  • Configuration
  • Providers
  • Discovery

• Contributing

  • Development Guide
  • Testing
  • Releases

💻 Examples

Working code examples you can run and modify:

• Basic MCP Server - Minimal MCP server with market data tools
• Paid API Example - Add x402 payments to Express API
• Trading Bot - Automated trading bot with RSI + MA strategy
• Full Deployment - Production-ready server with all features

Each example includes:

• Complete source code
• README with setup instructions
• Package configuration
• Environment setup guide

---

�🗺️ Roadmap

A comprehensive roadmap of all crypto/blockchain/DeFi/Web3 features to be implemented.

Legend

• ✅ Implemented
• 🚧 In Progress
• 📋 Planned

---

Data Sources

This MCP server integrates with the following APIs:

---

Related MCP Servers

Additional specialized MCP servers, maintained in their own repositories:

Binance.com Server

Full Binance global API coverage including:

• Spot trading, wallet, staking, mining
• Convert, Simple Earn, Algo Trading (TWAP/VP)
• NFT, Pay, Copy Trading, Dual Investment
• VIP Loans, C2C/P2P, Fiat

{
  "mcpServers": {
    "binance": {
      "command": "npx",
      "args": ["ts-node", "binance-mcp-server/src/index.ts"],
      "env": {
        "BINANCE_API_KEY": "your_key",
        "BINANCE_API_SECRET": "your_secret"
      }
    }
  }
}

Binance.US Server

US-regulated exchange with:

• Market data, spot trading, wallet
• Staking, OTC, sub-accounts
• Custodial solutions (institutional)

{
  "mcpServers": {
    "binance-us": {
      "command": "node",
      "args": ["binance-us-mcp-server/build/index.js"],
      "env": {
        "BINANCE_US_API_KEY": "your_key",
        "BINANCE_US_API_SECRET": "your_secret"
      }
    }
  }
}

---

Credits

Built by nich (github.com/nirholas)

---

🏢 Who’s Using This?

Universal Crypto MCP is used by developers and teams building:

• 🤖 AI Trading Bots - Automated portfolio management
• 📊 Analytics Dashboards - DeFi monitoring tools
• 🔒 Security Auditors - Token vetting workflows
• 🏦 DeFi Applications - Cross-chain operations
• 📱 Mobile Apps - Crypto portfolio trackers
• 🎓 Educational Tools - Blockchain learning platforms

Using Universal Crypto MCP? Let us know! We’d love to feature your project.

---

🤝 Contributing

We welcome contributions of all kinds! Please read our Contributing Guide for details.

Quick Start for Contributors

# Fork and clone the repo
git clone https://github.com/YOUR_USERNAME/universal-crypto-mcp.git
cd universal-crypto-mcp

# Install dependencies
npm install

# Create a feature branch
git checkout -b feat/your-feature

# Make your changes, then run checks
npm run lint          # Check code style
npm test              # Run tests
npm run test:coverage # Check coverage

# Commit with conventional commits
git commit -m "feat(module): add new feature"

# Push and create a PR
git push origin feat/your-feature

Code Style

We use Prettier for formatting and ESLint for linting:

npm run format    # Format code
npm run lint      # Check types and lint
npm run lint:fix  # Auto-fix issues

Ways to Contribute

• 🐛 Report bugs
• 💡 Request features
• 📖 Improve docs
• 🔧 Submit pull requests
• ⭐ Star the repo

---

📜 License

Apache-2.0 © nich

---

Stop copy-pasting blockchain queries. Let AI do it. Made with 💜 for the crypto community

---

🌐 Live HTTP Deployment

Universal Crypto MCP is deployed and accessible over HTTP via MCP Streamable HTTP transport — no local installation required.

Endpoint:

https://modelcontextprotocol.name/mcp/universal-crypto-mcp

Connect from any MCP Client

Add to your MCP client configuration (Claude Desktop, Cursor, SperaxOS, etc.):

{
  "mcpServers": {
    "universal-crypto-mcp": {
      "type": "http",
      "url": "https://modelcontextprotocol.name/mcp/universal-crypto-mcp"
    }
  }
}

Available Tools (11)

Example Requests

Get crypto prices:

curl -X POST https://modelcontextprotocol.name/mcp/universal-crypto-mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_price","arguments":{"ids":"bitcoin","vs_currencies":"usd"}}}'

Market overview:

curl -X POST https://modelcontextprotocol.name/mcp/universal-crypto-mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_market_overview","arguments":{"limit":10}}}'

Trending coins:

curl -X POST https://modelcontextprotocol.name/mcp/universal-crypto-mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_trending","arguments":{}}}'

List All Tools

curl -X POST https://modelcontextprotocol.name/mcp/universal-crypto-mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Also Available On

• SperaxOS — Browse and install from the MCP marketplace
• All 27 MCP servers — See the full catalog at modelcontextprotocol.name

Powered by modelcontextprotocol.name — the open MCP HTTP gateway