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

Live Demo · Quick Start · What Is This? · Components · Docs · Examples · FAQ

🧐 What Is This?

BNB Chain AI Toolkit gives AI assistants superpowers on the blockchain.

It's a single repository with everything you need to build AI-powered applications on BNB Chain — agents, blockchain connectors, market data, DeFi tools, wallets, and Web3 standards. All open source.

In plain English: Imagine giving Claude or ChatGPT a crypto wallet, a trading terminal, and 78 expert advisors. That's what this toolkit does.

New to crypto or AI? Start with our What Is This? guide — written for non-technical people.

Why This Toolkit?

| Problem | Solution | |---------|----------| | Fragmented BNB Chain tooling | Single repo with everything integrated | | AI can't interact with blockchains | 6 MCP servers give AI direct chain access | | Complex DeFi interactions | 78 specialized agents for every protocol | | Multi-chain complexity | Multi-chain support with unified interfaces | | No accessibility standards | W3AG + ERC-8004 for inclusive Web3 |

⚡ Quick Start

# Clone
git clone https://github.com/nirholas/bnb-chain-toolkit.git
cd bnb-chain-toolkit

# Install & build
bun install && bun run build

# Start any MCP server
cd mcp-servers/bnbchain-mcp && bun install && bun start

Use with Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "bnbchain": {
      "command": "npx",
      "args": ["-y", "@nirholas/bnbchain-mcp"],
      "env": {
        "BSC_RPC_URL": "https://bsc-dataseed.binance.org"
      }
    }
  }
}

📚 Full setup guide: Getting Started

🔗 Onchain Proof

ERC-8004 contracts are deployed and verified on BSC Mainnet, BSC Testnet.

BSC Mainnet (Chain ID: 56)

| Contract | Address | Explorer | |----------|---------|----------| | IdentityRegistry | 0x8004A169FB4a3325136EB29fA0ceB6D2e539a432 | BscScan → | | ReputationRegistry | 0x8004BAa17C55a88189AE136b182e5fdA19dE9b63 | BscScan → |

BSC Testnet (Chain ID: 97)

| Contract | Address | Explorer | |----------|---------|----------| | IdentityRegistry | 0x8004A818BFB912233c491871b3d84c89A494BD9e | BscScan → | | ReputationRegistry | 0x8004B663056A597Dffe9eCcC1965A193B7388713 | BscScan → | | ValidationRegistry | 0x8004Cb1BF31DAf7788923b405b754f57acEB4272 | BscScan → |

opBNB Testnet (Chain ID: 5611)

| Contract | Address | Explorer | |----------|---------|----------| | IdentityRegistry | 0x8004A818BFB912233c491871b3d84c89A494BD9e | opBNBScan → | | ReputationRegistry | 0x8004B663056A597Dffe9eCcC1965A193B7388713 | opBNBScan → | | ValidationRegistry | 0x8004Cb1BF31DAf7788923b405b754f57acEB4272 | opBNBScan → |

opBNB Mainnet (Chain ID: 204)

| Contract | Address | Explorer | |----------|---------|----------| | IdentityRegistry | 0x8004A169FB4a3325136EB29fA0ceB6D2e539a432 | opBNBScan → | | ReputationRegistry | 0x8004BAa17C55a88189AE136b182e5fdA19dE9b63 | opBNBScan → |

📋 First deployment TX: 0xfc55d83d...dc1962 on BSC Testnet

⚠️ Note: Smart contracts in standards/erc-8004/contracts/ are reference implementations and have not been formally audited. Do not deploy to mainnet without an independent security audit.

🏗️ Architecture

bnb-chain-toolkit/
├── agents/                     # 🤖 78 AI Agent definitions
│   ├── bnb-chain-agents/       #    36 BNB Chain-specific agents
│   └── defi-agents/            #    42 general DeFi agents (30+ languages)
│
├── mcp-servers/                # 🔌 6 Model Context Protocol servers
│   ├── bnbchain-mcp/           #    BNB Chain + EVM (466+ tools)
│   ├── binance-mcp/            #    Binance.com (554+ tools)
│   ├── binance-us-mcp/         #    Binance.US (US compliance)
│   ├── universal-crypto-mcp/   #    Multi-network (59+ tools)
│   ├── agenti/                 #    Universal EVM + Solana (58+ tools)
│   └── ucai/                   #    ABI-to-MCP generator (Python)
│
├── market-data/                # 📊 Market data & news
│   ├── crypto-market-data/     #    CoinGecko, DeFiLlama, Fear & Greed
│   └── crypto-news/            #    200+ sources, 150+ endpoints
│
├── defi-tools/                 # 🧹 DeFi utilities
│   └── sweep/                  #    Multi-chain dust sweeper
│
├── wallets/                    # 👛 Wallet tooling
│   └── ethereum-wallet-toolkit/#    Offline-capable, BSC compatible
│
├── standards/                  # 📜 Web3 standards
│   ├── erc-8004/               #    Agent discovery & trust protocol
│   └── w3ag/                   #    Web3 Accessibility Guidelines
│
└── docs/                       # 📖 Comprehensive documentation

📐 Deep dive: Architecture Guide

🧩 Components

🤖 AI Agents (78)

Pre-built agent definitions for every major BNB Chain protocol and DeFi use case.

| Agent | Description | |-------|-------------| | PancakeSwap Trader | DEX trading, liquidity, yield farming on PancakeSwap v3 | | Venus Protocol Expert | Lending, borrowing, liquidation on Venus | | BNB Staking Advisor | Liquid staking optimization across validators | | Binance Earn Specialist | Savings, staking, Launchpool yields | | BSC Bridge Navigator | Cross-chain bridging (BSC ↔ opBNB ↔ L2s) | | BEP-20 Token Analyst | Token security, smart money tracking | | Binance Copy Trading | Mirror top performers' strategies | | opBNB Scaling Expert | L2 gas optimization | | Greenfield Storage | Decentralized storage on BNB Greenfield | | Thena DEX Expert | ve(3,3) DEX trading on Thena | | + 26 more... | Full ecosystem coverage |

| Category | Count | Examples | |----------|:-----:|---------| | Portfolio Management | 8 | Tracking, rebalancing, tax optimization | | Trading Automation | 7 | Grid trading, DCA, arbitrage, signals | | Yield Optimization | 6 | Auto-compounding, IL protection | | Risk & Security | 5 | Auditing, rug detection | | Market Intelligence | 5 | Sentiment, whale tracking | | DeFi Protocols | 6 | Lending, DEX, derivatives | | Infrastructure | 5 | Bridge, gas, RPC, indexing |

📚 Full guide: Agents Documentation

🔌 MCP Servers (6)

Model Context Protocol servers that give AI assistants direct blockchain access.

| Server | Tools | What It Does | |--------|:-----:|-------------| | BNB Chain MCP | 466+ | BSC, opBNB, Greenfield — swaps, transfers, contracts | | Binance MCP | 554+ | Spot, futures, margin trading on Binance.com | | Binance US MCP | — | US regulatory-compliant Binance access | | Universal Crypto MCP | 59+ | Multi-network, cross-chain DeFi | | Agenti | — | EVM + Solana, AI-to-AI payments (x402) | | UCAI | Dynamic | Turn any smart contract ABI into an MCP server |

# One-command ABI-to-MCP conversion
ucai generate --abi ./Contract.json --chain bsc --output ./my-server

📚 Full guide: MCP Servers Documentation

📊 Market Data

| Component | Sources | Features | |-----------|:-------:|---------| | Crypto Market Data | CoinGecko, DeFiLlama, Fear & Greed | Zero-dependency, Edge Runtime compatible | | Crypto News | 200+ sources | 150+ endpoints, sentiment analysis, MCP server |

// Quick example
const btc = await CoinGecko.getPrice('bitcoin');
const fear = await FearAndGreed.getIndex();
console.log(`BTC: $${btc.usd} | Sentiment: ${fear.classification}`);

📚 Full guide: Market Data Documentation

🧹 DeFi Tools

Dust Sweeper — Scan 8 chains for tiny token balances, batch-swap them into stablecoins.

bun run scan --wallet 0xYourAddress --chain bsc    # Preview (safe)
bun run sweep --wallet 0xYourAddress --target USDC  # Execute

📚 Full guide: DeFi Tools Documentation

👛 Wallets

Ethereum Wallet Toolkit — Offline-capable, BSC-compatible wallet operations.

• HD wallet generation (BIP-39/44)
• Vanity address generation
• Message signing (EIP-191, EIP-712)
• Transaction signing (legacy + EIP-1559)
• Keystore V3 import/export

📚 Full guide: Wallets Documentation

📜 Standards

| Standard | Description | |----------|-------------| | ERC-8004 | On-chain AI agent discovery, reputation, and trust protocol | | W3AG | Web3 Accessibility Guidelines — making DeFi accessible to all |

📚 Full guide: Standards Documentation

🌐 Supported Networks

| Network | Type | Status | |---------|------|:------:| | BNB Smart Chain (BSC) | L1 | ✅ | | opBNB | L2 | ✅ | | BNB Greenfield | Storage | ✅ |

📊 Tool Summary

| Category | Count | Source | |----------|------:|--------| | BNB Chain + EVM on-chain tools | 466+ | bnbchain-mcp | | Binance exchange tools | 554+ | binance-mcp | | Cross-chain DeFi tools | 59+ | universal-crypto-mcp | | EVM chain tools | 58+ | agenti | | ABI-to-MCP generation | Dynamic | ucai | | Market data endpoints | 150+ | crypto-news + crypto-market-data | | Wallet operations | 20+ | ethereum-wallet-toolkit | | Total | 1,100+ | |

🛠️ Development

bun install           # Install dependencies
bun run build         # Build agent index
bun run format        # Format agent JSONs
bun run lint          # Lint TypeScript
bun run test          # Run tests
bun run type-check    # Type checking

Adding a New Agent

cp agents/bnb-chain-agents/agent-template.json agents/bnb-chain-agents/my-agent.json
# Edit the file, then:
bun run build

📚 Full guide: Creating Agents

📖 Documentation

| Guide | For | Description | |-------|-----|-------------| | What Is This? | Everyone | Simple explanation, no jargon | | Glossary | Everyone | terms explained in plain English | | Getting Started | Beginners | Step-by-step setup guide | | Architecture | Developers | System design & data flows | | Agents | Users | Complete agent catalog | | MCP Servers | Developers | Server setup & configuration | | Market Data | Developers | Price feeds & news APIs | | DeFi Tools | Users | Dust sweeping & utilities | | Wallets | Users | Wallet generation & signing | | Standards | Researchers | ERC-8004 & W3AG specs | | Examples | Everyone | Real-world usage patterns | | FAQ | Everyone | Common questions | | Troubleshooting | Everyone | Problem solving | | Awesome List | Everyone | Curated resources |

🤝 Contributing

Contributions are welcome! Whether it's a new agent, a bug fix, documentation improvement, or a new MCP server.

1. Fork the repo
2. Create your branch: git checkout -b feat/my-improvement
3. Commit: git commit -m "✨ feat: add amazing feature"
4. Push: git push origin feat/my-improvement
5. Open a Pull Request

📚 Full guide: CONTRIBUTING.md

📄 License

MIT © nirholas