Skip to content

Complete Documentation

Universal Crypto MCP - Full Documentation

This is a comprehensive guide to Universal Crypto MCP, the first AI-native blockchain infrastructure that combines a powerful MCP server with the x402 payment protocol.

📚 Documentation Structure

Getting Started

MCP Server

x402 Payment Protocol

Packages & Modules

Tutorials

Use Cases

🚀 Quick Navigation

By Role

AI Agent Developer 1. Installation 2. Quick Start 3. API Reference 4. Tutorials

API Developer 1. x402 Overview 2. Quick Start 3. Deployment Guide 4. Paid API Tutorial

Blockchain Developer 1. Architecture 2. Core Package 3. DeFi Package 4. Contributing

By Task

Setting Up - Install Universal Crypto MCP - Configure Environment - Connect to Claude

Blockchain Operations - Check Balances - Send Transactions - Swap Tokens - Query NFTs

Accepting Payments - Wrap Your API with x402 - Deploy to Production - Configure Pricing - Monitor Revenue

Building Projects - Trading Bot - Portfolio Tracker - DeFi Dashboard - Paid API

🔧 Core Concepts

Model Context Protocol (MCP)

MCP is an open protocol that standardizes how AI assistants connect to external data sources and tools.

Key Features: - JSON-RPC 2.0 based communication - Tool discovery and invocation - Resource management - Prompt templates

How it Works: 

sequenceDiagram
    participant AI as AI Agent (Claude)
    participant MCP as MCP Server
    participant BC as Blockchain

    AI->>MCP: List available tools
    MCP-->>AI: Returns 380+ blockchain tools
    AI->>MCP: Call tool: get_balance(address, chain)
    MCP->>BC: Query blockchain
    BC-->>MCP: Return balance data
    MCP-->>AI: Format and return result

x402 Payment Protocol

x402 is an HTTP 402-based protocol for AI agent payments using cryptocurrency.

Key Features: - HTTP 402 Payment Required status - On-chain payment verification - Automatic escrow and settlement - AI agent discovery network

How it Works: 

sequenceDiagram
    participant Agent as AI Agent
    participant API as Paid API
    participant Chain as Blockchain
    participant Facilitator as x402 Facilitator

    Agent->>API: GET /api/premium
    API-->>Agent: 402 Payment Required + price
    Agent->>Chain: Send payment transaction
    Chain-->>Agent: Transaction hash
    Agent->>API: GET /api/premium + x-payment header
    API->>Facilitator: Verify payment
    Facilitator->>Chain: Check transaction
    Chain-->>Facilitator: Confirmed
    Facilitator-->>API: Payment valid
    API-->>Agent: 200 OK + premium data

Multi-Chain Support

Universal Crypto MCP provides a unified interface for 20+ blockchain networks.

Supported Networks:

EVM Chains: - Ethereum (mainnet, sepolia, goerli) - Arbitrum (one, nova) - Base (mainnet, sepolia) - Polygon (mainnet, mumbai) - Optimism (mainnet, goerli) - BNB Chain (mainnet, testnet) - Avalanche (c-chain, fuji) - Fantom (mainnet, testnet) - zkSync Era - Linea - Scroll - Blast - Mode - Mantle

Other Chains: - Solana (mainnet, devnet, testnet)

DeFi Protocol Integration

Supported Protocols: - DEXes: Uniswap V2/V3, SushiSwap, PancakeSwap, Curve - Lending: Aave V2/V3, Compound V2/V3, Maker - Derivatives: GMX, Synthetix, dYdX - Yield: Yearn, Convex, Beefy

💡 Common Patterns

Pattern 1: Multi-Chain Balance Check

// Check balances across all supported chains
const chains = ['ethereum', 'arbitrum', 'base', 'polygon', 'optimism'];
const address = '0x...';

for (const chain of chains) {
  const balance = await getBalance(address, chain);
  console.log(`${chain}: ${balance} ETH`);
}

Pattern 2: Conditional Token Swap

// Swap ETH to USDC if price drops below threshold
const ethPrice = await getTokenPrice('ETH', 'USD');

if (ethPrice < 2000) {
  await swapTokens({
    from: 'ETH',
    to: 'USDC',
    amount: '0.5',
    chain: 'arbitrum'
  });
}

Pattern 3: Paid API with x402

import express from 'express';
import { wrapWithX402 } from '@nirholas/universal-crypto-mcp/x402';

const app = express();

// Regular API endpoint
app.get('/api/free', (req, res) => {
  res.json({ message: 'Free data' });
});

// Paid API endpoint
app.get('/api/premium', (req, res) => {
  res.json({ data: 'Premium content' });
});

// Wrap with x402 payment gateway
wrapWithX402(app, {
  pricing: {
    'GET /api/premium': '$0.001'
  },
  wallet: '0x...'
});

app.listen(3000);

Pattern 4: AI Agent Discovery

import { discoverServices } from '@nirholas/universal-crypto-mcp/x402';

// Find weather APIs under $0.01 per request
const services = await discoverServices({
  category: 'weather',
  maxPrice: '$0.01',
  minRating: 4.0
});

// Use the best service
const service = services[0];
const weather = await service.call('get_forecast', {
  city: 'New York'
}, {
  payment: {
    amount: service.price,
    token: 'USDC',
    network: 'arbitrum'
  }
});

Blockchain Operations

Token Operations

DeFi Operations

NFT Operations

Market Data

x402 Operations

🎓 Learning Path

Beginner Track

  1. Week 1: Setup & Basics
  2. Install Universal Crypto MCP
  3. First Transaction Tutorial

  4. Practice: Check balances, send small amounts

  5. Week 2: Multi-Chain

  6. Understanding Chains
  7. Cross-Chain Tutorial

  8. Practice: Query multiple chains, compare prices

  9. Week 3: DeFi Basics

  10. DeFi Overview
  11. Token Swap Tutorial

  12. Practice: Swap tokens, check liquidity

  13. Week 4: Build Project

  14. Trading Bot Tutorial
  15. Build your own simple bot
  16. Practice: Automated operations

Intermediate Track

  1. Payments & Monetization
  2. x402 Protocol Overview
  3. Create Paid API

  4. Build: Simple paid service

  5. Advanced DeFi

  6. Lending & Borrowing
  7. Yield Strategies

  8. Build: DeFi dashboard

  9. Security & Best Practices

  10. Security Guide
  11. Error Handling
  12. Build: Security scanner

Advanced Track

  1. Custom Integrations
  2. Architecture Deep Dive
  3. Plugin Development

  4. Build: Custom protocol integration

  5. Production Deployment

  6. Deployment Guide
  7. Scaling Strategies

  8. Deploy: Production service

  9. Contributing

  10. Contributing Guide
  11. Code Standards
  12. Contribute: PR to the project

🔗 External Resources

Community

📄 License

Universal Crypto MCP is open source under the Apache 2.0 License.

🤝 Support

Need help? Check these resources:

  1. FAQ - Frequently asked questions
  2. Troubleshooting - Common issues
  3. GitHub Issues - Bug reports
  4. Discussions - General questions
**[Get Started →](getting-started/installation.md)**