npm package: @iflow-mcp/nirholas-bnbchain-mcp
Description: Model Context Protocol (MCP) server for BNB Chain - BSC EVM and Greenfield decentralized storage
Author: nirholas
Latest version: 1.0.1

<div align="center">    

```  

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

```

<h1>BNB Chain MCP Server</h1>

<p><strong>The most comprehensive Model Context Protocol server for BNB Chain & EVM blockchains</strong></p>

<p>Enable AI agents to interact with BNB Chain, opBNB, and other EVM networks through natural language</p>

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
[![MCP](https://img.shields.io/badge/MCP-Compatible-purple?style=flat-square)](https://modelcontextprotocol.io)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue?style=flat-square&logo=typescript)](https://www.typescriptlang.org/)
[![BNB Chain](https://img.shields.io/badge/BNB_Chain-Native-F0B90B?style=flat-square&logo=binance)](https://www.bnbchain.org)

<br/>

[![BNB Chain](https://img.shields.io/badge/BNB_Chain-F0B90B?style=for-the-badge&logo=binance&logoColor=white)](https://www.bnbchain.org)
[![opBNB](https://img.shields.io/badge/opBNB-F0B90B?style=for-the-badge&logo=binance&logoColor=white)](https://opbnb.bnbchain.org)


<br/>

<!-- Animated Demo -->
<img src="assets/demo.svg" alt="BNB Chain MCP Demo" width="800">

<br/><br/>

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

<br/>

[📖 Documentation](https://bnb-chain-mcp.vercel.app) • [🚀 Quick Start](#-quick-start) • [🛠️ Features](#-features-overview) • [📊 Roadmap](#️-roadmap) • [🤝 Contributing](#-contributing)

</div>

---

## 📋 Table of Contents

- [What is BNB Chain MCP?](#-what-is-bnb-chain-mcp)
- [Quick Start](#-quick-start)
- [Features Overview](#-features-overview)
- [Supported Networks](#-supported-networks)
- [Installation](#-installation)
- [Configuration](#-configuration)
- [Data Sources](#-data-sources)
- [Example Conversations](#-example-conversations)
- [Architecture](#-architecture)
- [Roadmap](#️-roadmap)
- [Related MCP Servers](#-related-mcp-servers)
- [Troubleshooting](#-troubleshooting)
- [Contributing](#-contributing)
- [License](#-license)

---

## 🌟 What is BNB Chain MCP?

**BNB Chain MCP** is a Model Context Protocol (MCP) server optimized for BNB Chain and opBNB, while also supporting other EVM-compatible blockchains. It enables AI assistants like Claude, ChatGPT, and Cursor to interact with blockchain networks through natural language.

### Why BNB Chain MCP?

```
┌──────────────────────────────────────────────────────────────────────────────┐
│                                                                              │
│   User: "What's the current price of ETH and show me the best DEX pools"     │
│                                    │                                         │
│                                    ▼                                         │
│   ┌────────────────────────────────────────────────────────┐                 │
│   │              AI Assistant (Claude/ChatGPT)             │                 │
│   │                                                        │                 │
│   │         "Let me check that for you..."                 │                 │
│   └────────────────────────────────────────────────────────┘                 │
│                                    │                                         │
│                                    ▼                                         │
│   ┌───────────────────────────────────────────────────────┐                  │
│   │                  BNB Chain MCP Server                 │                  │
│   │                                                       │                  │
│   │   ┌──────────┐  ┌──────────┐  ┌──────────┐            │                  │
│   │   │CoinGecko │  │GeckoTerm │  │DefiLlama │   ...      │                  │
│   │   └────┬─────┘  └────┬─────┘  └────┬─────┘            │                  │
│   └────────┼─────────────┼─────────────┼──────────────────┘                  │
│            │             │             │                                     │
│            ▼             ▼             ▼                                     │
│   ┌────────────────────────────────────────────────────────┐                 │
│   │                  Blockchain Networks                   │                 │
│   │   BNB Chain  │  Ethereum  │  Arbitrum  │  Polygon      │                 │
│   └────────────────────────────────────────────────────────┘                 │
│                                                                              │
└──────────────────────────────────────────────────────────────────────────────┘
```

### Key Benefits

| Benefit | Description |
|---------|-------------|
| **Natural Language** | Ask questions in plain English, get blockchain data instantly |
| **Multi-Chain** | One server supports 10+ EVM networks simultaneously |
| **Read + Write** | Query data or execute transactions (with wallet) |
| **Security Built-In** | GoPlus integration for token/contract safety checks |
| **Rich Data** | Prices, DEX pools, TVL, social sentiment, news & more |
| **AI-Native** | Built specifically for LLMs with structured responses |

### Use Cases

<details>
<summary><strong>🔍 Research & Analysis</strong></summary>

- Check token prices and historical data
- Analyze DEX liquidity pools
- Monitor protocol TVL and metrics
- Research new tokens before investing
- Track whale wallets and movements

</details>

<details>
<summary><strong>💹 Trading & DeFi</strong></summary>

- Get swap quotes across DEX aggregators
- Find best yield farming opportunities
- Monitor lending rates on Aave/Compound
- Execute token swaps and transfers
- Bridge tokens across chains

</details>

<details>
<summary><strong>🛡️ Security & Compliance</strong></summary>

- Detect honeypot tokens
- Check for rug pull risks
- Verify smart contract safety
- Screen wallet addresses
- Check token holder distribution

</details>

<details>
<summary><strong>👨‍💻 Development</strong></summary>

- Deploy and verify smart contracts
- Query contract state and events
- Test transactions before execution
- Manage multi-sig operations
- Debug failed transactions

</details>

<br/>

<div align="center">
  <img src="assets/demo-defi.svg" alt="BNB Chain MCP DeFi Demo" width="800">
  <p><em>DeFi tools in action: swap quotes, TVL tracking, and more</em></p>
</div>

---

## 🚀 Quick Start

Get up and running in under 60 seconds!

### Option 1: Claude Desktop (Recommended)

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "bnb-chain-mcp": {
      "command": "npx",
      "args": ["-y", "@nirholas/bnb-chain-mcp@latest"]
    }
  }
}
```

<details>
<summary>📁 Config file locations</summary>

| OS | Path |
|----|------|
| **macOS** | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| **Windows** | `%APPDATA%\Claude\claude_desktop_config.json` |
| **Linux** | `~/.config/claude/claude_desktop_config.json` |

</details>

### Option 2: Cursor / VS Code

Add to your MCP settings:

```json
{
  "mcpServers": {
    "bnb-chain-mcp": {
      "command": "npx",
      "args": ["-y", "@nirholas/bnb-chain-mcp@latest"]
    }
  }
}
```

### Option 3: ChatGPT Developer Mode

1. Enable [Developer Mode](https://chatgpt.com/#settings/Connectors/Advanced) in ChatGPT settings
2. Start the HTTP server:
   ```bash
   npx @nirholas/bnb-chain-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

📖 [Full ChatGPT Setup Guide](https://bnb-chain-mcp.vercel.app/mcp-server/chatgpt-setup/)

### Option 4: npx Instant Start

```bash
# stdio mode (Claude, Cursor)
npx @nirholas/bnb-chain-mcp@latest

# HTTP mode (ChatGPT Developer Mode)
npx @nirholas/bnb-chain-mcp@latest --http

# SSE mode (legacy clients)
npx @nirholas/bnb-chain-mcp@latest --sse
```

---

## 🛠️ Features Overview

### Feature Matrix

| Category | Features | Status |
|----------|----------|--------|
| **Swap/DEX** | Token swaps via 1inch, 0x, ParaSwap | ✅ |
| **Bridge** | Cross-chain transfers via LayerZero, Stargate | ✅ |
| **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 integration | ✅ |
| **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 | ✅ |
| **MEV Protection** | Flashbots Protect, private transactions | ✅ |
| **ENS/Domains** | Register, transfer, renew, set records | ✅ |
| **Market Data** | CoinGecko prices, OHLCV, trending | ✅ |
| **DeFi Analytics** | DefiLlama TVL, yields, fees, protocols | ✅ |
| **Social Sentiment** | LunarCrush metrics, influencers, trending | ✅ |
| **DEX Analytics** | GeckoTerminal pools, trades, OHLCV | ✅ |

### Tool Categories

<details>
<summary><strong>🔗 Core Blockchain (45+ tools)</strong></summary>

| Tool | Description |
|------|-------------|
| `get_chain_info` | Get chain ID, block number, gas price |
| `get_block` | Get block by number or hash |
| `get_transaction` | Get transaction details and receipt |
| `send_transaction` | Send native token transfer |
| `estimate_gas` | Estimate gas for transaction |
| `get_balance` | Get native/token balance |
| `call_contract` | Call view/pure contract functions |
| ... | [See full list →](https://bnb-chain-mcp.vercel.app/tools/blockchain) |

</details>

<details>
<summary><strong>💰 Token Operations (30+ tools)</strong></summary>

| Tool | Description |
|------|-------------|
| `get_token_info` | Get name, symbol, decimals, supply |
| `get_token_balance` | Get token balance for address |
| `transfer_token` | Transfer ERC-20 tokens |
| `approve_token` | Approve spending allowance |
| `get_nft_metadata` | Get NFT metadata and traits |
| `transfer_nft` | Transfer ERC-721 NFT |
| ... | [See full list →](https://bnb-chain-mcp.vercel.app/tools/tokens) |

</details>

<details>
<summary><strong>🏦 DeFi (50+ tools)</strong></summary>

| Tool | Description |
|------|-------------|
| `get_swap_quote` | Get swap quote from DEX aggregators |
| `execute_swap` | Execute token swap |
| `add_liquidity` | Add liquidity to DEX pools |
| `get_lending_rates` | Get Aave/Compound rates |
| `supply_to_lending` | Supply assets to lending protocol |
| `get_farming_apy` | Get yield farming APY |
| ... | [See full list →](https://bnb-chain-mcp.vercel.app/tools/defi) |

</details>

<details>
<summary><strong>🔒 Security (15+ tools)</strong></summary>

| Tool | Description |
|------|-------------|
| `check_token_security` | GoPlus token security analysis |
| `detect_honeypot` | Check if token is honeypot |
| `check_rug_pull` | Assess rug pull risk |
| `get_holder_distribution` | Get top holder breakdown |
| `check_contract_verified` | Verify contract source |
| `screen_address` | Check address risk score |
| ... | [See full list →](https://bnb-chain-mcp.vercel.app/tools/security) |

</details>

<details>
<summary><strong>📊 Market Data (25+ tools)</strong></summary>

| Tool | Description |
|------|-------------|
| `get_price` | Get current token price |
| `get_price_history` | Get historical OHLCV data |
| `get_trending_coins` | Get trending tokens |
| `get_tvl` | Get protocol TVL from DefiLlama |
| `get_dex_pools` | Get DEX pool data |
| `get_social_metrics` | Get LunarCrush sentiment |
| ... | [See full list →](https://bnb-chain-mcp.vercel.app/tools/market-data) |

</details>

---

## 🌐 Supported Networks

| Network | Chain ID | Native Token | Status |
|---------|----------|--------------|--------|
| **BNB Smart Chain** | 56 | BNB | ✅ Full Support |
| **opBNB** | 204 | BNB | ✅ Full Support |
| **Arbitrum One** | 42161 | ETH | ✅ Full Support |
| **Ethereum** | 1 | ETH | ✅ Full Support |
| **Polygon** | 137 | MATIC | ✅ Full Support |
| **Base** | 8453 | ETH | ✅ Full Support |
| **Optimism** | 10 | ETH | ✅ Full Support |
| **Avalanche C-Chain** | 43114 | AVAX | ✅ Full Support |
| **Fantom** | 250 | FTM | ✅ Full Support |
| **Gnosis** | 100 | xDAI | ✅ Full Support |
| **BSC Testnet** | 97 | tBNB | ✅ Testnet |
| **Sepolia** | 11155111 | SepoliaETH | ✅ Testnet |
| **Goerli** | 5 | GoerliETH | ✅ Testnet |

### Adding Custom Networks

```json
{
  "mcpServers": {
    "bnb-chain-mcp": {
      "command": "npx",
      "args": ["-y", "@nirholas/bnb-chain-mcp@latest"],
      "env": {
        "CUSTOM_RPC_56": "https://your-bnb-rpc.com",
        "CUSTOM_RPC_1": "https://your-eth-rpc.com"
      }
    }
  }
}
```

---

## 📦 Installation

### Server Modes

| Mode | Command | Use Case |
|------|---------|----------|
| **stdio** | `npx @nirholas/bnb-chain-mcp` | Claude Desktop, Cursor |
| **HTTP** | `npx @nirholas/bnb-chain-mcp --http` | ChatGPT Developer Mode |
| **SSE** | `npx @nirholas/bnb-chain-mcp --sse` | Legacy HTTP clients |

### From npm (Recommended)

```bash
# Run directly with npx (no install required)
npx @nirholas/bnb-chain-mcp@latest

# Or install globally
npm install -g @nirholas/bnb-chain-mcp

# Then run
bnb-chain-mcp
```

### From Source

```bash
# Clone
git clone https://github.com/nirholas/bnb-chain-mcp
cd bnb-chain-mcp

# Install dependencies
bun install

# Build
bun run build

# Run dev server (stdio - Claude)
bun dev

# Run dev server (HTTP - ChatGPT)
bun dev:http

# Run dev server (SSE - legacy)
bun dev:sse
```

### Docker

```bash
# Build
docker build -t bnb-chain-mcp .

# Run stdio mode
docker run -it bnb-chain-mcp

# Run HTTP mode
docker run -p 3001:3001 bnb-chain-mcp --http
```

---

## ⚙️ Configuration

### Environment Variables

| Variable | Description | Default | Required |
|----------|-------------|---------|----------|
| `PRIVATE_KEY` | Wallet private key for transactions | - | No (read-only without) |
| `COINGECKO_API_KEY` | CoinGecko Pro API key | - | No |
| `COINSTATS_API_KEY` | CoinStats API key | - | No |
| `LUNARCRUSH_API_KEY` | LunarCrush API key | - | No |
| `CRYPTOPANIC_API_KEY` | CryptoPanic news API key | - | No |
| `CUSTOM_RPC_<CHAIN_ID>` | Custom RPC for specific chain | - | No |
| `PORT` | HTTP server port | 3001 | No |
| `LOG_LEVEL` | Logging level | info | No |

### Full Configuration Example

```json
{
  "mcpServers": {
    "bnb-chain-mcp": {
      "command": "npx",
      "args": ["-y", "@nirholas/bnb-chain-mcp@latest"],
      "env": {
        "PRIVATE_KEY": "0x...",
        "COINGECKO_API_KEY": "CG-xxx",
        "LUNARCRUSH_API_KEY": "xxx",
        "CUSTOM_RPC_56": "https://bsc-rpc.publicnode.com",
        "CUSTOM_RPC_1": "https://eth-rpc.publicnode.com",
        "LOG_LEVEL": "debug"
      }
    }
  }
}
```

### Claude Desktop Configuration

<details>
<summary><strong>macOS</strong></summary>

```bash
# Open config file
open ~/Library/Application\ Support/Claude/claude_desktop_config.json
```

</details>

<details>
<summary><strong>Windows</strong></summary>

```powershell
# Open config file
notepad %APPDATA%\Claude\claude_desktop_config.json
```

</details>

<details>
<summary><strong>Linux</strong></summary>

```bash
# Open config file
nano ~/.config/claude/claude_desktop_config.json
```

</details>

---

## 📊 Data Sources

This MCP server integrates with the following APIs:

| Provider | Data Type | API Key | Rate Limits |
|----------|-----------|---------|-------------|
| [CoinGecko](https://coingecko.com) | Market data, prices, OHLCV | Optional | 10-50 req/min |
| [CoinStats](https://coinstats.app) | Portfolio, prices, wallets | Required | Varies |
| [DefiLlama](https://defillama.com) | TVL, yields, fees, protocols | No | Generous |
| [LunarCrush](https://lunarcrush.com) | Social sentiment, influencers | Required | Varies |
| [GoPlus](https://gopluslabs.io) | Security analysis, honeypot | No | Generous |
| [GeckoTerminal](https://geckoterminal.com) | DEX pools, trades, OHLCV | No | Generous |
| [DexPaprika](https://dexpaprika.com) | DEX analytics, pools | No | Generous |
| [CryptoPanic](https://cryptopanic.com) | Crypto news | Required | Varies |
| [Alternative.me](https://alternative.me) | Fear & Greed Index | No | Generous |

---

## 💬 Example Conversations

### Price Queries

> **User:** "What's the current price of BNB?"
>
> **AI:** *Uses `get_price` tool* → "BNB is currently trading at $XXX.XX, up 2.5% in the last 24 hours."

### Security Checks

> **User:** "Is this token safe? 0x..."
>
> **AI:** *Uses `check_token_security` and `detect_honeypot`* → "⚠️ Warning: This token has several red flags..."

### DEX Analysis

> **User:** "Show me the best BNB liquidity pools"
>
> **AI:** *Uses `get_dex_pools`* → "Here are the top pools on BNB Chain by TVL..."

### Multi-Chain Portfolio

> **User:** "Check my wallet across all chains: 0x..."
>
> **AI:** *Uses `get_portfolio`* → "Your total portfolio value is $X across 5 chains..."

### DeFi Research

> **User:** "What are the best yield farming opportunities on BNB Chain?"
>
> **AI:** *Uses `get_yield_farms` and `get_tvl`* → "Here are the top yield opportunities..."

---

## 🏗️ Architecture

```
┌──────────────────────────────────────────────────────────────────────────────┐
│                          BNB Chain MCP Server                                │
├──────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐                        │
│  │    stdio     │  │     HTTP     │  │      SSE     │   Transport Layer      │
│  │   (Claude)   │  │   (ChatGPT)  │  │   (Legacy)   │                        │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘                        │
│         │                 │                 │                                │
│         └─────────────────┼─────────────────┘                                │
│                           │                                                  │
│                           ▼                                                  │
│  ┌───────────────────────────────────────────────────────────────────────┐   │
│  │                        MCP Protocol Handler                           │   │
│  │     Tools Registration  |  Resource Management  |  Prompt Templates   │   │
│  └───────────────────────────────────────────────────────────────────────┘   │
│                           │                                                  │
│         ┌─────────────────┼─────────────────┐                                │
│         ▼                 ▼                 ▼                                │
│  ┌────────────┐    ┌────────────┐    ┌────────────┐                          │
│  │ Blockchain │    │   Market   │    │  Security  │    Tool Categories       │
│  │   Tools    │    │    Data    │    │   Tools    │                          │
│  └─────┬──────┘    └─────┬──────┘    └─────┬──────┘                          │
│        │                 │                 │                                 │
│        ▼                 ▼                 ▼                                 │
│  ┌───────────────────────────────────────────────────────────────────────┐   │
│  │                         Provider Integrations                         │   │
│  │   viem | CoinGecko | DefiLlama | GoPlus | LunarCrush | GeckoTerminal  │   │
│  └───────────────────────────────────────────────────────────────────────┘   │
│                           │                                                  │
│                           ▼                                                  │
│  ┌───────────────────────────────────────────────────────────────────────┐   │
│  │                           EVM Networks                                │   │
│  │   BNB Chain | Ethereum | Arbitrum | Polygon | Base | Optimism | ...   │   │
│  └───────────────────────────────────────────────────────────────────────┘   │
│                                                                              │
└──────────────────────────────────────────────────────────────────────────────┘
```

### Module Organization

```
src/
├── index.ts              # Entry point
├── server/
│   ├── stdio.ts          # stdio transport
│   ├── http.ts           # HTTP transport
│   └── sse.ts            # SSE transport
├── tools/
│   ├── blockchain/       # Core chain operations
│   ├── tokens/           # Token operations
│   ├── defi/             # DeFi protocols
│   ├── security/         # Security checks
│   ├── market/           # Market data
│   └── social/           # Social sentiment
├── providers/
│   ├── coingecko.ts      # CoinGecko API
│   ├── defillama.ts      # DefiLlama API
│   ├── goplus.ts         # GoPlus Security
│   └── ...
└── utils/
    ├── chains.ts         # Chain configurations
    ├── abi.ts            # Common ABIs
    └── format.ts         # Formatters
```

---

## 🔐 Security

### Security Model

| Feature | Description |
|---------|-------------|
| **Read-Only Mode** | Without `PRIVATE_KEY`, server only reads blockchain state |
| **No Key Storage** | Private keys are never stored, only used in memory |
| **Input Validation** | All inputs validated with Zod schemas |
| **Rate Limiting** | Built-in rate limiting prevents API abuse |
| **Verified Sources** | Only uses reputable data providers |

### Best Practices

- ⚠️ **Never share** your `PRIVATE_KEY` in public configs
- ✅ Use environment variables or secrets management
- ✅ Use read-only mode when possible
- ✅ Always verify token safety before interacting
- ✅ Review transaction simulations before executing

---

## ❓ Troubleshooting

<details>
<summary><strong>Server won't start</strong></summary>

1. Check Node.js version (requires 18+):
   ```bash
   node --version
   ```
2. Clear npx cache:
   ```bash
   npx clear-npx-cache
   ```
3. Try installing globally:
   ```bash
   npm install -g @nirholas/bnb-chain-mcp
   ```

</details>

<details>
<summary><strong>Claude Desktop doesn't see the server</strong></summary>

1. Verify config file location and JSON syntax
2. Restart Claude Desktop completely
3. Check logs:
   - macOS: `~/Library/Logs/Claude/mcp*.log`
   - Windows: `%APPDATA%\Claude\logs\mcp*.log`

</details>

<details>
<summary><strong>RPC errors / Rate limiting</strong></summary>

1. Use a dedicated RPC provider (Alchemy, QuickNode, etc.)
2. Configure custom RPC:
   ```json
   "env": {
     "CUSTOM_RPC_56": "https://your-dedicated-rpc.com"
   }
   ```

</details>

<details>
<summary><strong>API key errors</strong></summary>

1. Verify API key is correct (no extra spaces)
2. Check API key has required permissions
3. Verify rate limits haven't been exceeded

</details>

---

## 🗺️ Roadmap

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

### Legend
- ✅ Implemented
- 🚧 In Progress
- 📋 Planned

---

### 🔗 Core Blockchain Operations

#### Network & Chain
| Feature | Status |
|---------|--------|
| Get chain ID, block number, gas price | ✅ |
| Get network status/health | ✅ |
| Switch networks/chains | ✅ |
| Get supported networks list | ✅ |
| Get RPC endpoints | ✅ |
| Estimate block time | ✅ |
| Get chain metadata (name, symbol, explorers) | ✅ |
| Get finality status | ✅ |
| Get mempool/pending transactions | ✅ |
| Get network peers/nodes | ✅ |
| Get gas oracle | ✅ |

#### Blocks
| Feature | Status |
|---------|--------|
| Get block by number/hash | ✅ |
| Get latest block | ✅ |
| Get block transactions | ✅ |
| Get block receipts | ✅ |
| Get uncle blocks | ✅ |
| Subscribe to new blocks | 📋 |
| Get block rewards | ✅ |
| Get block gas used/limit | ✅ |
| Get block range | ✅ |
| Get blocks by miner | ✅ |

#### Transactions
| Feature | Status |
|---------|--------|
| Send transaction | ✅ |
| Get transaction by hash | ✅ |
| Get transaction receipt | ✅ |
| Get transaction status | ✅ |
| Estimate gas | ✅ |
| Speed up transaction (replace with higher gas) | ✅ |
| Cancel transaction | ✅ |
| Decode transaction input | ✅ |
| Simulate transaction | ✅ |
| Get transaction trace | 📋 |
| Get internal transactions | 📋 |
| Batch transactions | ✅ |
| Get pending transactions | ✅ |
| Get transaction history by address | ✅ |

#### Accounts/Wallets
| Feature | Status |
|---------|--------|
| Get balance (native/token) | ✅ |
| Get nonce | ✅ |
| Get transaction count | ✅ |
| Create wallet | ✅ |
| Import wallet (private key/mnemonic) | ✅ |
| Export private key | 📋 |
| Sign message | ✅ |
| Verify signature | ✅ |
| Get address from private key | ✅ |
| Generate mnemonic | ✅ |
| Derive addresses (HD wallet) | ✅ |
| Multi-sig wallet operations | 📋 |
| Get wallet permissions | 📋 |
| Revoke approvals | ✅ |
| Account abstraction (ERC-4337) | 📋 |
| Social recovery | 📋 |
| Hardware wallet integration | 📋 |
| Get wallet portfolio | ✅ |
| Get token approvals | ✅ |

---

### 💰 Token Operations

#### Native Tokens
| Feature | Status |
|---------|--------|
| Get native balance | ✅ |
| Transfer native tokens | ✅ |
| Wrap/unwrap native tokens (WETH, WBNB) | ✅ |

#### ERC-20 (Fungible Tokens)
| Feature | Status |
|---------|--------|
| Get token info (name, symbol, decimals, total supply) | ✅ |
| Get token balance | ✅ |
| Transfer tokens | ✅ |
| Approve spending | ✅ |
| Get allowance | ✅ |
| Transfer from (delegated) | ✅ |
| Burn tokens | ✅ |
| Mint tokens | ✅ |
| Get token holders | ✅ |
| Get token transfers | ✅ |
| Permit (gasless approvals - EIP-2612) | ✅ |
| Batch transfers | ✅ |
| Token snapshots | 📋 |
| Get token supply info | ✅ |
| Check/revoke token approval | ✅ |

#### ERC-721 (NFTs)
| Feature | Status |
|---------|--------|
| Get NFT metadata | ✅ |
| Get NFT owner | ✅ |
| Transfer NFT | ✅ |
| Approve NFT | ✅ |
| Set approval for all | ✅ |
| Get NFTs by owner | ✅ |
| Get NFT collection info | ✅ |
| Mint NFT | 📋 |
| Burn NFT | 📋 |
| Get NFT transfer history | 📋 |
| Get NFT traits/attributes | ✅ |
| Get NFT rarity | 📋 |
| Verify NFT authenticity | 📋 |
| Batch transfer NFTs | ✅ |
| Check NFT approval | ✅ |
| Revoke NFT approval | ✅ |
| Approve for marketplace | ✅ |
| Fetch NFT metadata from URI | ✅ |

#### ERC-1155 (Multi-Token)
| Feature | Status |
|---------|--------|
| Get token balance (fungible + NFT) | ✅ |
| Batch transfers | 📋 |
| Batch balance queries | 📋 |
| Safe transfer | ✅ |
| Get URI | ✅ |

#### Other Token Standards
| Feature | Status |
|---------|--------|
| ERC-777 (advanced fungible) | 📋 |
| ERC-3525 (semi-fungible) | 📋 |
| ERC-4626 (tokenized vaults) | 📋 |
| ERC-6551 (token-bound accounts) | 📋 |
| ERC-404 (hybrid tokens) | 📋 |
| Soulbound tokens (SBTs) | 📋 |

---

### 🏦 DeFi - Decentralized Exchanges (DEX)

#### Swaps
| Feature | Status |
|---------|--------|
| Get quote/price | ✅ |
| Swap exact tokens for tokens | ✅ |
| Swap tokens for exact tokens | ✅ |
| Multi-hop swaps | ✅ |
| Split route swaps | 📋 |
| Cross-DEX aggregation | ✅ |
| Limit orders | 📋 |
| TWAP orders (time-weighted) | 📋 |
| Stop-loss orders | 📋 |
| Get slippage estimate | ✅ |
| Get price impact | ✅ |
| MEV protection (private transactions) | 📋 |

#### DEX Analytics
| Feature | Status |
|---------|--------|
| Get trending pools | ✅ |
| Get new pools | ✅ |
| Get top pools by volume | ✅ |
| Get pool OHLCV data | ✅ |
| Get pool trades | ✅ |
| Get token pools | ✅ |
| Get DEX list | ✅ |
| Search pools cross-chain | ✅ |
| Get token price by contract | ✅ |
| Get pool transactions | ✅ |
| Multi-token price lookup | ✅ |

#### Liquidity Provision
| Feature | Status |
|---------|--------|
| Add liquidity | ✅ |
| Remove liquidity | ✅ |
| Get LP token balance | ✅ |
| Get pool reserves | ✅ |
| Get pool APY/APR | 📋 |
| Get impermanent loss estimate | 📋 |
| Concentrated liquidity (Uniswap V3) | 📋 |
| Set price range | 📋 |
| Collect fees | 📋 |
| Rebalance position | 📋 |
| Add liquidity with native token | ✅ |
| Calculate arbitrage opportunities | ✅ |

#### AMM Types Support
| Feature | Status |
|---------|--------|
| Constant product (x*y=k) | ✅ |
| Stable swap (Curve) | 📋 |
| Concentrated liquidity | 📋 |
| Order book hybrid | 📋 |
| Virtual AMM (perpetuals) | 📋 |

---

### 🏦 DeFi - Lending & Borrowing

#### Lending
| Feature | Status |
|---------|--------|
| Supply/deposit assets | ✅ |
| Withdraw assets | ✅ |
| Get supply APY | ✅ |
| Get supplied balance | ✅ |
| Get utilization rate | 📋 |
| Enable/disable as collateral | 📋 |

#### Borrowing
| Feature | Status |
|---------|--------|
| Borrow assets | ✅ |
| Repay debt | ✅ |
| Get borrow APY | ✅ |
| Get borrowed balance | ✅ |
| Get health factor | ✅ |
| Get liquidation threshold | ✅ |
| Get max borrowable amount | 📋 |
| Flash loans | ✅ |
| Get borrow limit | 📋 |
| Get flash loan info | ✅ |

#### Liquidations
| Feature | Status |
|---------|--------|
| Liquidate unhealthy positions | 📋 |
| Get liquidatable positions | ✅ |
| Get liquidation bonus | 📋 |
| Partial liquidations | 📋 |

#### Isolated Markets
| Feature | Status |
|---------|--------|
| Supply to isolated pool | 📋 |
| Borrow from isolated pool | 📋 |
| Get isolation mode debt ceiling | 📋 |

---

### 🥩 DeFi - Staking

#### Native Staking
| Feature | Status |
|---------|--------|
| Stake native tokens | ✅ |
| Unstake/withdraw | ✅ |
| Claim rewards | ✅ |
| Get staking APY | ✅ |
| Get validator list | 📋 |
| Delegate to validator | 📋 |
| Redelegate | 📋 |
| Get unbonding period | 📋 |

#### Liquid Staking
| Feature | Status |
|---------|--------|
| Stake for liquid staking tokens (stETH, rETH) | ✅ |
| Unwrap liquid staking tokens | ✅ |
| Get exchange rate | ✅ |
| Get staking rewards rate | ✅ |

#### LP Staking/Farming
| Feature | Status |
|---------|--------|
| Stake LP tokens | ✅ |
| Unstake LP tokens | ✅ |
| Claim farming rewards | ✅ |
| Get farming APY | ✅ |
| Compound rewards | 📋 |
| Get pending rewards | ✅ |
| Boost rewards (veTokens) | 📋 |

#### Restaking
| Feature | Status |
|---------|--------|
| Restake assets (EigenLayer) | 📋 |
| Get restaking points | 📋 |
| Choose operators | 📋 |
| Withdraw from restaking | 📋 |

---

### 📊 DeFi - Derivatives

#### Perpetual Futures
| Feature | Status |
|---------|--------|
| Open long/short position | 📋 |
| Close position | 📋 |
| Add/remove margin | 📋 |
| Set leverage | 📋 |
| Get funding rate | 📋 |
| Get open interest | 📋 |
| Get liquidation price | 📋 |
| Set stop-loss/take-profit | 📋 |
| Get PnL | 📋 |
| Partial close | 📋 |

#### Options
| Feature | Status |
|---------|--------|
| Buy call/put options | 📋 |
| Sell/write options | 📋 |
| Exercise options | 📋 |
| Get option greeks | 📋 |
| Get implied volatility | 📋 |
| Get option chain | 📋 |
| Spread strategies | 📋 |

#### Synthetics
| Feature | Status |
|---------|--------|
| Mint synthetic assets | 📋 |
| Burn synthetic assets | 📋 |
| Get collateral ratio | 📋 |
| Get synthetic price feed | 📋 |
| Liquidate synthetic positions | 📋 |

---

### 🌉 Cross-Chain & Bridges

#### Bridging
| Feature | Status |
|---------|--------|
| Bridge tokens cross-chain | ✅ |
| Get bridge quote | ✅ |
| Get bridge status | ✅ |
| Get supported chains | ✅ |
| Get supported tokens | ✅ |
| Claim bridged tokens | 📋 |
| Get bridge fees | ✅ |
| Get estimated time | ✅ |

#### Cross-Chain Messaging
| Feature | Status |
|---------|--------|
| Send cross-chain message | 📋 |
| Receive cross-chain message | 📋 |
| LayerZero operations | 📋 |
| Axelar operations | 📋 |
| Wormhole operations | 📋 |
| CCIP (Chainlink) | 📋 |
| Hyperlane operations | 📋 |

#### Atomic Swaps
| Feature | Status |
|---------|--------|
| Initiate atomic swap | 📋 |
| Complete atomic swap | 📋 |
| Refund atomic swap | 📋 |

---

### 🗳️ Governance

#### Voting
| Feature | Status |
|---------|--------|
| Create proposal | ✅ |
| Vote on proposal | ✅ |
| Delegate votes | ✅ |
| Get voting power | ✅ |
| Get proposal state | ✅ |
| Queue proposal | ✅ |
| Execute proposal | ✅ |
| Cancel proposal | ✅ |
| Get vote receipt | ✅ |

#### Token Locking
| Feature | Status |
|---------|--------|
| Lock tokens for voting (veTokens) | 📋 |
| Extend lock period | 📋 |
| Increase locked amount | 📋 |
| Withdraw unlocked tokens | 📋 |
| Get lock info | 📋 |

#### Snapshot (Off-chain)
| Feature | Status |
|---------|--------|
| Create space | 📋 |
| Create off-chain proposal | 📋 |
| Vote off-chain | 📋 |
| Get snapshot results | 📋 |

---

### 🔐 Security & Analysis

#### Contract Analysis
| Feature | Status |
|---------|--------|
| Verify contract source | ✅ |
| Get contract ABI | ✅ |
| Check if contract is proxy | ✅ |
| Get implementation address | ✅ |
| Detect honeypots | ✅ |
| Check for rug pull risks | ✅ |
| GoPlus token security check | ✅ |
| GoPlus rug pull detection | ✅ |
| Audit score | 📋 |
| Get contract creator | ✅ |
| Get contract age | ✅ |
| Detect malicious functions | ✅ |

#### Token Security
| Feature | Status |
|---------|--------|
| Check token safety | ✅ |
| Get holder distribution | ✅ |
| Check if mintable | ✅ |
| Check if pausable | ✅ |
| Check for hidden fees | ✅ |
| Check liquidity locked | ✅ |
| Get top holders | ✅ |
| Check ownership renounced | ✅ |
| GoPlus NFT security | ✅ |
| GoPlus approval security | ✅ |

#### Wallet Security
| Feature | Status |
|---------|--------|
| Get approval list | ✅ |
| Revoke approvals | ✅ |
| Check for drainers | ✅ |
| Simulate transaction safety | ✅ |
| Get wallet risk score | 📋 |
| GoPlus address security | ✅ |
| GoPlus dApp phishing check | ✅ |
| GoPlus signature decode | ✅ |

---

### 📈 Price & Market Data

#### Price Feeds
| Feature | Status |
|---------|--------|
| Get current price | ✅ |
| Get historical prices | ✅ |
| Get OHLCV data | ✅ |
| Get price from DEX | ✅ |
| Get price from oracle (Chainlink, Pyth) | ✅ |
| Get TWAP price | ✅ |
| Get price across exchanges | ✅ |
| Get volume | ✅ |
| Get market cap | ✅ |
| Get trending coins | ✅ |
| Get token by contract address | ✅ |
| Get exchange rates | ✅ |
| Get coin categories | ✅ |
| Get derivatives data | ✅ |
| Get company BTC/ETH holdings | ✅ |

#### Analytics
| Feature | Status |
|---------|--------|
| Get TVL (Total Value Locked) | ✅ |
| Get protocol metrics | ✅ |
| Get yield farming APYs | ✅ |
| Get gas tracker | ✅ |
| Get whale transactions | 📋 |
| Get token flow analysis | 📋 |
| Get DEX volume | ✅ |
| Get lending metrics | 📋 |
| Get DeFi fees & revenue | ✅ |
| Get stablecoin data | ✅ |
| Get bridge volumes | ✅ |
| Get liquidation data | ✅ |
| Get DeFi hacks history | ✅ |
| Get perpetuals data | ✅ |

---

### 🆔 Identity & Domains

#### ENS (Ethereum Name Service)
| Feature | Status |
|---------|--------|
| Register domain | ✅ |
| Resolve name to address | ✅ |
| Reverse resolve address to name | ✅ |
| Set primary name | 📋 |
| Set records (text, address, content hash) | ✅ |
| Transfer domain | ✅ |
| Renew domain | ✅ |
| Get expiry date | 📋 |
| Set subdomains | ✅ |

#### Other Name Services
| Feature | Status |
|---------|--------|
| Unstoppable Domains | 📋 |
| Space ID (.bnb) | 📋 |
| Bonfida (.sol) | 📋 |
| ANS (.avax) | 📋 |

#### DIDs & Verifiable Credentials
| Feature | Status |
|---------|--------|
| Create DID | 📋 |
| Resolve DID | 📋 |
| Issue verifiable credential | 📋 |
| Verify credential | 📋 |
| Revoke credential | 📋 |

---

### 🖼️ NFT & Metaverse

#### NFT Marketplace
| Feature | Status |
|---------|--------|
| List NFT for sale | 📋 |
| Buy NFT | 📋 |
| Make offer | 📋 |
| Accept offer | 📋 |
| Cancel listing | 📋 |
| Auction NFT | 📋 |
| Bid on auction | 📋 |
| Get floor price | 📋 |
| Get collection stats | 📋 |

#### NFT Creation
| Feature | Status |
|---------|--------|
| Deploy NFT collection | 📋 |
| Mint NFTs | 📋 |
| Set royalties | 📋 |
| Set metadata | 📋 |
| Reveal NFTs | 📋 |
| Whitelist management | 📋 |
| Airdrop NFTs | 📋 |

#### NFT Finance
| Feature | Status |
|---------|--------|
| NFT collateralized loans | 📋 |
| NFT fractionalization | 📋 |
| NFT renting | 📋 |
| NFT staking | 📋 |

#### Metaverse
| Feature | Status |
|---------|--------|
| Buy virtual land | 📋 |
| Sell virtual land | 📋 |
| Build on land | 📋 |
| Transfer assets between metaverses | 📋 |

---

### 🔔 Events & Subscriptions

#### Event Listening
| Feature | Status |
|---------|--------|
| Subscribe to contract events | 📋 |
| Subscribe to pending transactions | 📋 |
| Subscribe to new blocks | 📋 |
| Subscribe to logs | 📋 |
| Filter events by topic | ✅ |
| Get historical events | ✅ |
| Decode event logs | ✅ |

#### Webhooks & Notifications
| Feature | Status |
|---------|--------|
| Set up webhook for events | 📋 |
| Get transaction notifications | 📋 |
| Get price alerts | 📋 |
| Get whale alerts | 📋 |
| Get governance notifications | 📋 |

---

### 📜 Smart Contract Interaction

#### Read Operations
| Feature | Status |
|---------|--------|
| Call view/pure functions | ✅ |
| Get storage at slot | ✅ |
| Get contract bytecode | ✅ |
| Multicall (batch reads) | ✅ |
| Static call simulation | ✅ |

#### Write Operations
| Feature | Status |
|---------|--------|
| Send transaction to contract | ✅ |
| Encode function call | ✅ |
| Decode function result | ✅ |
| Estimate gas for call | ✅ |
| Batch transactions | ✅ |

#### Contract Deployment
| Feature | Status |
|---------|--------|
| Deploy contract | ✅ |
| Deploy with CREATE2 | ✅ |
| Deploy proxy contract | ✅ |
| Upgrade proxy | ✅ |
| Verify on explorer | ✅ |

---

### 🤖 Advanced Features

#### MEV & Flashbots
| Feature | Status |
|---------|--------|
| Submit private transaction | ✅ |
| Submit bundle | ✅ |
| Get MEV opportunities | ✅ |
| Backrun protection | ✅ |
| Frontrun protection | ✅ |
| Sandwich protection | ✅ |

#### Account Abstraction (ERC-4337)
| Feature | Status |
|---------|--------|
| Create smart account | 📋 |
| Execute user operation | 📋 |
| Batch operations | 📋 |
| Sponsor gas (Paymaster) | 📋 |
| Session keys | 📋 |
| Social recovery | 📋 |

#### Intents & Solvers
| Feature | Status |
|---------|--------|
| Submit intent | 📋 |
| Get solver quotes | 📋 |
| Execute via solver | 📋 |

#### Oracles
| Feature | Status |
|---------|--------|
| Get Chainlink price | ✅ |
| Get Pyth price | 📋 |
| Get Band Protocol price | 📋 |
| Get API3 price | 📋 |
| Request randomness (VRF) | 📋 |
| Request external data | 📋 |

---

### 🛠️ Utility Functions

#### Gas
| Feature | Status |
|---------|--------|
| Get gas price | ✅ |
| Get priority fee | ✅ |
| Get base fee | ✅ |
| Get gas history | ✅ |
| Estimate gas for transaction | ✅ |
| Get EIP-1559 fees | ✅ |

#### Encoding/Decoding
| Feature | Status |
|---------|--------|
| ABI encode | ✅ |
| ABI decode | ✅ |
| Keccak256 hash | ✅ |
| Pack/unpack data | ✅ |
| Sign typed data (EIP-712) | ✅ |

#### Address Utils
| Feature | Status |
|---------|--------|
| Validate address | ✅ |
| Checksum address | ✅ |
| Get address from ENS | ✅ |
| Check if contract | ✅ |
| Get contract type | 📋 |

---

### 📰 Data & Information

#### News & Social
| Feature | Status |
|---------|--------|
| Get crypto news | ✅ |
| Search crypto news | ✅ |
| Get DeFi news | ✅ |
| Get Bitcoin news | ✅ |
| Get breaking news | ✅ |
| Get social sentiment | ✅ |
| Get influencer rankings | ✅ |
| Get trending topics | ✅ |
| Get coin social metrics | ✅ |
| Get social feed | ✅ |
| Get market sentiment index | ✅ |
| Get Galaxy Score | ✅ |
| Get AltRank | ✅ |
| Get Twitter mentions | 📋 |
| Get Discord activity | 📋 |
| Get GitHub activity | 📋 |

#### On-Chain Data
| Feature | Status |
|---------|--------|
| Get token holders | 📋 |
| Get whale wallets | 📋 |
| Get smart money movements | 📋 |
| Get protocol users | 📋 |
| Get daily active addresses | 📋 |
| Get network hash rate | 📋 |

---

### 🏛️ Institutional & Compliance

#### KYC/AML
| Feature | Status |
|---------|--------|
| Wallet screening | 📋 |
| Transaction monitoring | 📋 |
| Risk scoring | 📋 |
| Sanctions checking | 📋 |

#### Custody
| Feature | Status |
|---------|--------|
| Multi-sig operations | 📋 |
| Cold storage | 📋 |
| Hot wallet management | 📋 |
| Policy enforcement | 📋 |

#### Reporting
| Feature | Status |
|---------|--------|
| Tax reporting | 📋 |
| Portfolio tracking | ✅ |
| P&L reporting | 📋 |
| Transaction history export | 📋 |

---

## Data Sources

This MCP server integrates with the following APIs:

| Provider | Data Type | API Key Required |
|----------|-----------|------------------|
| [CoinGecko](https://coingecko.com) | Market data, prices, OHLCV | Optional (free tier) |
| [CoinStats](https://coinstats.app) | Portfolio, prices, wallets | Yes |
| [DefiLlama](https://defillama.com) | TVL, yields, fees, protocols | No |
| [LunarCrush](https://lunarcrush.com) | Social sentiment, influencers | Yes |
| [GoPlus](https://gopluslabs.io) | Security analysis, honeypot detection | No |
| [GeckoTerminal](https://geckoterminal.com) | DEX pools, trades, OHLCV | No |
| [DexPaprika](https://dexpaprika.com) | DEX analytics, pools | No |
| [CryptoPanic](https://cryptopanic.com) | Crypto news | Yes |
| [Alternative.me](https://alternative.me) | Fear & Greed Index | No |

---

## 🔗 Related MCP Servers

Additional specialized MCP servers in this workspace:

| Server | Description | Tools |
|--------|-------------|-------|
| [binance-mcp-server](./binance-mcp-server/) | Binance.com global exchange API | 156+ tools |
| [binance-us-mcp-server](./binance-us-mcp-server/) | Binance.US exchange API | 71+ tools |

### 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

```json
{
  "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)

```json
{
  "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"
      }
    }
  }
}
```

---

## 🤝 Contributing

We welcome contributions! Here's how to get started:

### Development Setup

```bash
# Fork and clone
git clone https://github.com/YOUR_USERNAME/bnb-chain-mcp
cd bnb-chain-mcp

# Install dependencies
bun install

# Create feature branch
git checkout -b feature/amazing-feature

# Make changes and test
bun dev
bun test

# Commit and push
git commit -m "feat: add amazing feature"
git push origin feature/amazing-feature

# Open Pull Request
```

### Contribution Guidelines

- 📝 Follow existing code style
- ✅ Add tests for new features
- 📖 Update documentation
- 🔍 Run linting before committing

### Adding New Tools

1. Create tool file in `src/tools/<category>/`
2. Export tool definition with Zod schema
3. Add to tool index
4. Document in README

---

## 📄 License

This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.

---

## 🙏 Credits

Built by **[nich](https://x.com/nichxbt)** ([github.com/nirholas](https://github.com/nirholas)) **[and the Sperax Team](https://x.com/SperaxUSD)** ([github.com/speraxos](https://github.com/speraxos)) ([github.com/sperax](https://github.com/sperax))

### Special Thanks

- [Model Context Protocol](https://modelcontextprotocol.io) team
- [viem](https://viem.sh) for excellent EVM tooling
- All the amazing Web3 API providers

---

<div align="center">

### 🌟 Star us on GitHub!

If you find this project useful, please consider giving it a ⭐️

[![GitHub stars](https://img.shields.io/github/stars/nirholas/bnb-chain-mcp?style=social)](https://github.com/nirholas/bnb-chain-mcp)

<br/>

<sub>Empowering AI agents to interact with blockchains</sub>

</div>

<details>
<summary>.</summary>
# ERC-8004 Keywords & SEO Terms

> Comprehensive keyword list for ERC-8004 Trustless Agents ecosystem

---

## Core Protocol Keywords

ERC-8004, ERC8004, EIP-8004, EIP8004, Trustless Agents, trustless agent, trustless AI, trustless AI agents, agent protocol, agent standard, Ethereum agent standard, blockchain agent protocol, on-chain agents, onchain agents, on-chain AI, onchain AI, decentralized agents, decentralized AI agents, autonomous agents, autonomous AI agents, AI agent protocol, AI agent standard, agent discovery, agent trust, agent reputation, agent validation, agent identity, agent registry, identity registry, reputation registry, validation registry, agent NFT, ERC-721 agent, agent tokenId, agentId, agentURI, agentWallet, agent registration, agent registration file, agent-registration.json, agent card, agent metadata, agent endpoints, agent discovery protocol, agent trust protocol, open agent protocol, open agent standard, permissionless agents, permissionless AI, censorship-resistant agents, portable agent identity, portable AI identity, verifiable agents, verifiable AI agents, accountable agents, accountable AI, agent accountability

## Blockchain & Web3 Keywords

Ethereum, Ethereum mainnet, ETH, EVM, Ethereum Virtual Machine, smart contracts, Solidity, blockchain, decentralized, permissionless, trustless, on-chain, onchain, L2, Layer 2, Base, Optimism, Polygon, Linea, Arbitrum, Scroll, Monad, Gnosis, Celo, Sepolia, testnet, mainnet, singleton contracts, singleton deployment, ERC-721, NFT, non-fungible token, tokenURI, URIStorage, EIP-712, ERC-1271, wallet signature, EOA, smart contract wallet, gas fees, gas sponsorship, EIP-7702, subgraph, The Graph, indexer, blockchain indexing, IPFS, decentralized storage, content-addressed, immutable data, public registry, public good, credibly neutral, credibly neutral infrastructure, open protocol, open standard, Web3, crypto, cryptocurrency, DeFi, decentralized finance

## AI & Agent Technology Keywords

AI agents, artificial intelligence agents, autonomous AI, AI autonomy, LLM agents, large language model agents, machine learning agents, ML agents, AI assistant, AI chatbot, intelligent agents, software agents, digital agents, virtual agents, AI automation, automated agents, agent-to-agent, A2A, A2A protocol, Google A2A, Agent2Agent, MCP, Model Context Protocol, agent communication, agent interoperability, agent orchestration, agent collaboration, multi-agent, multi-agent systems, agent capabilities, agent skills, agent tools, agent prompts, agent resources, agent completions, AgentCard, agent card, agent endpoint, agent service, AI service, AI API, agent API, AI infrastructure, agent infrastructure, agentic, agentic web, agentic economy, agentic commerce, agent economy, agent marketplace, AI marketplace, agent platform, AI platform

## Trust & Reputation Keywords

trust, trustless, reputation, reputation system, reputation protocol, reputation registry, feedback, client feedback, user feedback, on-chain feedback, on-chain reputation, verifiable reputation, portable reputation, reputation aggregation, reputation scoring, reputation algorithm, trust signals, trust model, trust verification, trust layer, recursive reputation, reviewer reputation, spam prevention, Sybil attack, Sybil resistance, anti-spam, feedback filtering, trusted reviewers, rating, rating system, quality rating, starred rating, uptime rating, success rate, response time, performance history, track record, audit trail, immutable feedback, permanent feedback, feedback response, appendResponse, giveFeedback, revokeFeedback, feedback tags, feedback value, valueDecimals, feedbackURI, feedbackHash, clientAddress, reviewer address

## Validation & Verification Keywords

validation, validation registry, validator, validator contract, cryptographic validation, cryptographic proof, cryptographic attestation, zero-knowledge, ZK, zkML, zero-knowledge machine learning, ZK proofs, trusted execution environment, TEE, TEE attestation, TEE oracle, stake-secured, staking validators, crypto-economic security, inference re-execution, output validation, work verification, third-party validation, independent validation, validation request, validation response, validationRequest, validationResponse, requestHash, responseHash, verifiable computation, verified agents, verified behavior, behavioral validation, agent verification

## Payment & Commerce Keywords

x402, x402 protocol, x402 payments, programmable payments, micropayments, HTTP payments, pay-per-request, pay-per-task, agent payments, AI payments, agent monetization, AI monetization, agent commerce, AI commerce, agentic commerce, agent economy, AI economy, agent marketplace, service marketplace, agent-to-agent payments, A2A payments, stablecoin payments, USDC, crypto payments, on-chain payments, payment settlement, programmable settlement, proof of payment, proofOfPayment, payment receipt, payment verification, Coinbase, Coinbase x402, agent pricing, API pricing, service pricing, subscription, API keys, revenue, trading yield, cumulative revenues, agent wallet, payment address, toAddress, fromAddress, txHash

## Discovery & Registry Keywords

agent discovery, service discovery, agent registry, identity registry, agent registration, register agent, mint agent, agent NFT, agent tokenId, agent browsing, agent explorer, agent scanner, 8004scan, 8004scan.io, agentscan, agentscan.info, 8004agents, 8004agents.ai, agent leaderboard, agent ranking, top agents, agent listing, agent directory, agent catalog, agent index, browse agents, search agents, find agents, discover agents, agent visibility, agent discoverability, no-code registration, agent creation, create agent, my agents, agent owner, agent operator, agent transfer, transferable agent, portable agent

## Endpoints & Integration Keywords

endpoint, agent endpoint, service endpoint, API endpoint, MCP endpoint, A2A endpoint, web endpoint, HTTPS endpoint, HTTP endpoint, DID, decentralized identifier, ENS, Ethereum Name Service, ENS name, agent.eth, vitalik.eth, email endpoint, OASF, Open Agent Specification Format, endpoint verification, domain verification, endpoint ownership, .well-known, well-known, agent-registration.json, endpoint domain, endpoint URL, endpoint URI, base64 data URI, on-chain metadata, off-chain metadata, metadata storage, JSON metadata, agent JSON, registration JSON

## SDK & Developer Tools Keywords

SDK, Agent0 SDK, Agent0, ChaosChain SDK, ChaosChain, Lucid Agents, Daydreams AI, create-8004-agent, npm, TypeScript SDK, Python SDK, JavaScript, Solidity, smart contract, ABI, contract ABI, deployed contracts, contract addresses, Hardhat, development tools, developer tools, dev tools, API, REST API, GraphQL, subgraph, The Graph, indexer, blockchain explorer, Etherscan, contract verification, open source, MIT license, CC0, public domain, GitHub, repository, code repository, documentation, docs, best practices, reference implementation

## Ecosystem & Community Keywords

ecosystem, community, builder, builders, developer, developers, contributor, contributors, partner, partners, collaborator, collaborators, co-author, co-authors, MetaMask, Ethereum Foundation, Google, Coinbase, Consensys, AltLayer, Virtuals Protocol, Olas, EigenLayer, Phala, ElizaOS, Flashbots, Polygon, Base, Optimism, Arbitrum, Scroll, Linea, Monad, Gnosis, Celo, Near Protocol, Filecoin, Worldcoin, ThirdWeb, ENS, Collab.land, DappRadar, Giza Tech, Theoriq, OpenServ, Questflow, Semantic, Semiotic, Cambrian, Nevermined, Oasis, Towns Protocol, Warden Protocol, Terminal3, Pinata Cloud, Silence Labs, Rena Labs, Index Network, Trusta Network, Turf Network

## Key People & Organizations Keywords

Marco De Rossi, MetaMask AI Lead, Davide Crapis, Ethereum Foundation AI, Head of AI, Jordan Ellis, Google engineer, Erik Reppel, Coinbase engineering, Head of Engineering, Sumeet Chougule, ChaosChain founder, YQ, AltLayer co-founder, Wee Kee, Virtuals contributor, Cyfrin audit, Nethermind audit, Ethereum Foundation Security Team, security audit, audited contracts

## Use Cases & Applications Keywords

trading bot, DeFi agent, yield optimizer, data oracle, price feed, analytics agent, research agent, coding agent, development agent, automation agent, task agent, workflow agent, portfolio management, asset management, supply chain, service agent, API service, chatbot, AI assistant, virtual assistant, personal agent, enterprise agent, B2B agent, agent-as-a-service, AaaS, SaaS agent, AI SaaS, delegated agent, proxy agent, helper agent, worker agent, coordinator agent, orchestrator agent, validator agent, auditor agent, insurance agent, scoring agent, ranking agent

## Technical Specifications Keywords

ERC-8004 specification, EIP specification, Ethereum Improvement Proposal, Ethereum Request for Comment, RFC 2119, RFC 8174, MUST, SHOULD, MAY, OPTIONAL, REQUIRED, interface, contract interface, function signature, event, emit event, indexed event, storage, contract storage, view function, external function, public function, uint256, int128, uint8, uint64, bytes32, string, address, array, struct, MetadataEntry, mapping, modifier, require, revert, transfer, approve, operator, owner, tokenId, URI, hash, keccak256, KECCAK-256, signature, deadline

## Events & Conferences Keywords

8004 Launch Day, Agentic Brunch, Builder Nights Denver, Trustless Agent Day, Devconnect, ETHDenver, community call, meetup, hackathon, workshop, conference, summit, builder program, grants, bounties, ecosystem fund

## News & Media Keywords

announcement, launch, mainnet launch, testnet launch, protocol update, upgrade, security review, audit, milestone, breaking news, ecosystem news, agent news, AI news, blockchain news, Web3 news, crypto news, DeFi news, newsletter, blog, article, press release, media coverage

## Competitor & Alternative Keywords

agent framework, agent platform, AI platform, centralized agents, closed agents, proprietary agents, gatekeeper, intermediary, platform lock-in, vendor lock-in, data silos, walled garden, open alternative, decentralized alternative, permissionless alternative, trustless alternative

## Future & Roadmap Keywords

cross-chain, multi-chain, chain agnostic, bridge, interoperability, governance, community governance, decentralized governance, DAO, protocol upgrade, upgradeable contracts, UUPS, proxy contract, ERC1967Proxy, protocol evolution, standard finalization, EIP finalization, mainnet feedback, testnet feedback, security improvements, gas optimization, feature request, enhancement, proposal

---

## Long-tail Keywords & Phrases

how to register AI agent on blockchain, how to create ERC-8004 agent, how to build trustless AI agent, how to verify agent reputation, how to give feedback to AI agent, how to monetize AI agent, how to accept crypto payments AI agent, how to discover AI agents, how to trust AI agents, how to validate AI agent output, decentralized AI agent marketplace, on-chain AI agent registry, blockchain-based AI reputation, verifiable AI agent identity, portable AI agent reputation, permissionless AI agent registration, trustless AI agent discovery, autonomous AI agent payments, agent-to-agent micropayments, AI agent service discovery, AI agent trust protocol, open source AI agent standard, Ethereum AI agent protocol, EVM AI agent standard, blockchain AI agent framework, decentralized AI agent infrastructure, Web3 AI agent ecosystem, crypto AI agent platform, DeFi AI agent integration, NFT-based agent identity, ERC-721 agent registration, on-chain agent metadata, off-chain agent data, IPFS agent storage, subgraph agent indexing, agent explorer blockchain, agent scanner Ethereum, agent leaderboard ranking, agent reputation scoring, agent feedback system, agent validation proof, zkML agent verification, TEE agent attestation, stake-secured agent validation, x402 agent payments, MCP agent endpoint, A2A agent protocol, ENS agent name, DID agent identity, agent wallet address, agent owner operator, transferable agent NFT, portable agent identity, censorship-resistant agent registry, credibly neutral agent infrastructure, public good agent data, open agent economy, agentic web infrastructure, trustless agentic commerce, autonomous agent economy, AI agent economic actors, accountable AI agents, verifiable AI behavior, auditable AI agents, transparent AI agents, decentralized AI governance, community-driven AI standards, open protocol AI agents, permissionless AI innovation

---

## Brand & Product Keywords

8004, 8004.org, Trustless Agents, trustlessagents, trustless-agents, 8004scan, 8004scan.io, agentscan, agentscan.info, 8004agents, 8004agents.ai, Agent0, agent0, sdk.ag0.xyz, ChaosChain, chaoschain, docs.chaoscha.in, Lucid Agents, lucid-agents, daydreams.systems, create-8004-agent, erc-8004-contracts, best-practices, agent0lab, subgraph

---

## Hashtags & Social Keywords

#ERC8004, #TrustlessAgents, #AIAgents, #DecentralizedAI, #OnChainAI, #AgenticWeb, #AgentEconomy, #Web3AI, #BlockchainAI, #EthereumAI, #CryptoAI, #AutonomousAgents, #AIAutonomy, #AgentDiscovery, #AgentTrust, #AgentReputation, #x402, #MCP, #A2A, #AgentProtocol, #OpenAgents, #PermissionlessAI, #VerifiableAI, #AccountableAI, #AIInfrastructure, #AgentInfrastructure, #BuildWithAgents, #AgentBuilders, #AgentDevelopers, #AgentEcosystem

---

## Statistical Keywords

10000+ agents, 10300+ agents, 10000+ testnet registrations, 20000+ feedback, 5 months development, 80+ teams, 100+ partners, January 28 2026, January 29 2026, mainnet live, production ready, audited contracts, singleton deployment, per-chain singleton, ERC-721 token, NFT minting, gas fees, $5-20 mainnet gas

---

## Additional Core Protocol Terms

ERC 8004, EIP 8004, trustless agent protocol, trustless agent standard, trustless agent framework, trustless agent system, trustless agent network, trustless agent infrastructure, trustless agent architecture, trustless agent specification, trustless agent implementation, trustless agent deployment, trustless agent integration, trustless agent ecosystem, trustless agent platform, trustless agent marketplace, trustless agent registry, trustless agent identity, trustless agent reputation, trustless agent validation, trustless agent discovery, trustless agent verification, trustless agent authentication, trustless agent authorization, trustless agent registration, trustless agent management, trustless agent operations, trustless agent services, trustless agent solutions, trustless agent technology, trustless agent innovation, trustless agent development, trustless agent research, trustless agent security, trustless agent privacy, trustless agent transparency, trustless agent accountability, trustless agent governance, trustless agent compliance, trustless agent standards, trustless agent protocols, trustless agent interfaces, trustless agent APIs, trustless agent SDKs, trustless agent tools, trustless agent utilities, trustless agent libraries, trustless agent modules, trustless agent components, trustless agent extensions

## Extended Blockchain Terms

Ethereum blockchain, Ethereum network, Ethereum protocol, Ethereum ecosystem, Ethereum infrastructure, Ethereum development, Ethereum smart contract, Ethereum dApp, Ethereum application, Ethereum transaction, Ethereum gas, Ethereum wallet, Ethereum address, Ethereum account, Ethereum signature, Ethereum verification, Ethereum consensus, Ethereum finality, Ethereum block, Ethereum chain, Ethereum node, Ethereum client, Ethereum RPC, Ethereum JSON-RPC, Ethereum Web3, Ethereum ethers.js, Ethereum viem, Ethereum wagmi, Ethereum hardhat, Ethereum foundry, Ethereum truffle, Ethereum remix, Ethereum deployment, Ethereum verification, Ethereum explorer, Ethereum scanner, Base blockchain, Base network, Base L2, Base layer 2, Base mainnet, Base testnet, Base Sepolia, Optimism blockchain, Optimism network, Optimism L2, Optimism mainnet, Optimism Sepolia, Polygon blockchain, Polygon network, Polygon PoS, Polygon zkEVM, Polygon mainnet, Polygon Mumbai, Arbitrum blockchain, Arbitrum One, Arbitrum Nova, Arbitrum Sepolia, Arbitrum Stylus, Linea blockchain, Linea network, Linea mainnet, Linea testnet, Scroll blockchain, Scroll network, Scroll mainnet, Scroll Sepolia, Monad blockchain, Monad network, Monad testnet, Gnosis Chain, Gnosis Safe, Celo blockchain, Celo network, Avalanche, Fantom, BNB Chain, BSC, Binance Smart Chain, zkSync, StarkNet, Mantle, Blast, Mode, Zora, opBNB, Manta, Taiko

## Extended AI Agent Terms

artificial intelligence agent, machine learning agent, deep learning agent, neural network agent, transformer agent, GPT agent, Claude agent, Gemini agent, Llama agent, Mistral agent, AI model agent, foundation model agent, language model agent, multimodal agent, vision agent, audio agent, speech agent, text agent, code agent, coding assistant, programming agent, developer agent, software agent, application agent, web agent, mobile agent, desktop agent, cloud agent, edge agent, IoT agent, robotic agent, automation agent, workflow agent, process agent, task agent, job agent, worker agent, assistant agent, helper agent, support agent, service agent, utility agent, tool agent, function agent, capability agent, skill agent, knowledge agent, reasoning agent, planning agent, decision agent, execution agent, monitoring agent, logging agent, analytics agent, reporting agent, notification agent, alert agent, scheduling agent, calendar agent, email agent, messaging agent, chat agent, conversation agent, dialogue agent, interactive agent, responsive agent, reactive agent, proactive agent, predictive agent, adaptive agent, learning agent, evolving agent, self-improving agent, autonomous agent system, multi-agent architecture, agent swarm, agent collective, agent network, agent cluster, agent pool, agent fleet, agent army, agent workforce, agent team, agent group, agent ensemble, agent coalition, agent federation, agent consortium, agent alliance, agent partnership, agent collaboration, agent cooperation, agent coordination, agent orchestration, agent choreography, agent composition, agent aggregation, agent integration, agent interoperability, agent compatibility, agent standardization, agent normalization, agent harmonization

## Extended Trust & Reputation Terms

trust protocol, trust system, trust network, trust infrastructure, trust layer, trust framework, trust model, trust algorithm, trust computation, trust calculation, trust score, trust rating, trust level, trust tier, trust grade, trust rank, trust index, trust metric, trust indicator, trust signal, trust factor, trust weight, trust coefficient, trust threshold, trust minimum, trust maximum, trust average, trust median, trust distribution, trust aggregation, trust normalization, trust scaling, trust decay, trust growth, trust accumulation, trust history, trust timeline, trust evolution, trust trajectory, trust prediction, trust forecast, trust estimation, trust inference, trust derivation, trust propagation, trust transfer, trust delegation, trust inheritance, trust chain, trust path, trust graph, trust network analysis, trust community detection, trust clustering, trust similarity, trust distance, trust proximity, trust relationship, trust connection, trust link, trust edge, trust node, trust vertex, reputation protocol, reputation system, reputation network, reputation infrastructure, reputation layer, reputation framework, reputation model, reputation algorithm, reputation computation, reputation calculation, reputation score, reputation rating, reputation level, reputation tier, reputation grade, reputation rank, reputation index, reputation metric, reputation indicator, reputation signal, reputation factor, reputation weight, reputation coefficient, reputation threshold, reputation minimum, reputation maximum, reputation average, reputation median, reputation distribution, reputation aggregation, reputation normalization, reputation scaling, reputation decay, reputation growth, reputation accumulation, reputation history, reputation timeline, reputation evolution, reputation trajectory, reputation prediction, reputation forecast, reputation estimation, reputation inference, reputation derivation, reputation propagation,