# Bnb Chain Toolkit

> A modular toolkit for building, deploying, and interacting with smart contracts on BNB Chain. Includes utilities for BEP-20 tokens, DeFi integrations, wallet management, and cross-chain bridging. Built by Sperax team for BNB Chain Hackathon.

- **Type:** MCP server
- **Install:** `agentstack add mcp-nirholas-bnb-chain-toolkit`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [nirholas](https://agentstack.voostack.com/s/nirholas)
- **Installs:** 0
- **Category:** [Finance & Payments](https://agentstack.voostack.com/c/finance-and-payments)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [nirholas](https://github.com/nirholas)
- **Source:** https://github.com/nirholas/bnb-chain-toolkit
- **Website:** https://erc8004.agency/

## Install

```sh
agentstack add mcp-nirholas-bnb-chain-toolkit
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

```

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

🔶 The most comprehensive open-source AI toolkit for BNB Chain

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?](docs/what-is-this.md) 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

```bash
# 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`:

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

> 📚 **Full setup guide:** [Getting Started](docs/getting-started.md)

---

## 🔗 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 →](https://bscscan.com/address/0x8004A169FB4a3325136EB29fA0ceB6D2e539a432) |
| **ReputationRegistry** | `0x8004BAa17C55a88189AE136b182e5fdA19dE9b63` | [BscScan →](https://bscscan.com/address/0x8004BAa17C55a88189AE136b182e5fdA19dE9b63) |

### BSC Testnet (Chain ID: 97)

| Contract | Address | Explorer |
|----------|---------|----------|
| **IdentityRegistry** | `0x8004A818BFB912233c491871b3d84c89A494BD9e` | [BscScan →](https://testnet.bscscan.com/address/0x8004A818BFB912233c491871b3d84c89A494BD9e) |
| **ReputationRegistry** | `0x8004B663056A597Dffe9eCcC1965A193B7388713` | [BscScan →](https://testnet.bscscan.com/address/0x8004B663056A597Dffe9eCcC1965A193B7388713) |
| **ValidationRegistry** | `0x8004Cb1BF31DAf7788923b405b754f57acEB4272` | [BscScan →](https://testnet.bscscan.com/address/0x8004Cb1BF31DAf7788923b405b754f57acEB4272) |

### opBNB Testnet (Chain ID: 5611)

| Contract | Address | Explorer |
|----------|---------|----------|
| **IdentityRegistry** | `0x8004A818BFB912233c491871b3d84c89A494BD9e` | [opBNBScan →](https://testnet.opbnbscan.com/address/0x8004A818BFB912233c491871b3d84c89A494BD9e) |
| **ReputationRegistry** | `0x8004B663056A597Dffe9eCcC1965A193B7388713` | [opBNBScan →](https://testnet.opbnbscan.com/address/0x8004B663056A597Dffe9eCcC1965A193B7388713) |
| **ValidationRegistry** | `0x8004Cb1BF31DAf7788923b405b754f57acEB4272` | [opBNBScan →](https://testnet.opbnbscan.com/address/0x8004Cb1BF31DAf7788923b405b754f57acEB4272) |

### opBNB Mainnet (Chain ID: 204)

| Contract | Address | Explorer |
|----------|---------|----------|
| **IdentityRegistry** | `0x8004A169FB4a3325136EB29fA0ceB6D2e539a432` | [opBNBScan →](https://opbnbscan.com/address/0x8004A169FB4a3325136EB29fA0ceB6D2e539a432) |
| **ReputationRegistry** | `0x8004BAa17C55a88189AE136b182e5fdA19dE9b63` | [opBNBScan →](https://opbnbscan.com/address/0x8004BAa17C55a88189AE136b182e5fdA19dE9b63) |

> 📋 **First deployment TX:** [`0xfc55d83d...dc1962`](https://testnet.bscscan.com/tx/0xfc55d83d20e6d92ff522f302fd3424d3fd5557f25c06f4bfc38ecf3246dc1962) 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](docs/architecture.md)

---

## 🧩 Components

### 🤖 AI Agents (78)

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

BNB Chain Agents (36) — Click to expand

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

DeFi Agents (42) — Click to expand

| 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](docs/agents.md)

---

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

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

> 📚 **Full guide:** [MCP Servers Documentation](docs/mcp-servers.md)

---

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

```typescript
// 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](docs/market-data.md)

---

### 🧹 DeFi Tools

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

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

> 📚 **Full guide:** [DeFi Tools Documentation](docs/defi-tools.md)

---

### 👛 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](docs/wallets.md)

---

### 📜 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](docs/standards.md)

---

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

```bash
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

```bash
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](docs/agents.md#creating-your-own-agent)

---

## 📖 Documentation

| Guide | For | Description |
|-------|-----|-------------|
| [What Is This?](docs/what-is-this.md) | Everyone | Simple explanation, no jargon |
| [Glossary](docs/GLOSSARY.md) | Everyone |  terms explained in plain English |
| [Getting Started](docs/getting-started.md) | Beginners | Step-by-step setup guide |
| [Architecture](docs/architecture.md) | Developers | System design & data flows |
| [Agents](docs/agents.md) | Users | Complete agent catalog |
| [MCP Servers](docs/mcp-servers.md) | Developers | Server setup & configuration |
| [Market Data](docs/market-data.md) | Developers | Price feeds & news APIs |
| [DeFi Tools](docs/defi-tools.md) | Users | Dust sweeping & utilities |
| [Wallets](docs/wallets.md) | Users | Wallet generation & signing |
| [Standards](docs/standards.md) | Researchers | ERC-8004 & W3AG specs |
| [Examples](docs/examples.md) | Everyone | Real-world usage patterns |
| [FAQ](docs/faq.md) | Everyone | Common questions |
| [Troubleshooting](docs/troubleshooting.md) | Everyone | Problem solving |
| [Awesome List](docs/awesome.md) | 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](https://github.com/nirholas/bnb-chain-toolkit/pulls)

> 📚 **Full guide:** [CONTRIBUTING.md](CONTRIBUTING.md)

---

## 📄 License

MIT © [nirholas](https://github.com/nirholas)

---

  Built with 🔶 for BNB Chain
  78 agents · 6 MCP servers · 1,100+ tools · 30+ languages

  
  ⭐ Found this useful? Star the repo! ⭐
  It helps others discover this project and keeps development active

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [nirholas](https://github.com/nirholas)
- **Source:** [nirholas/bnb-chain-toolkit](https://github.com/nirholas/bnb-chain-toolkit)
- **License:** MIT
- **Homepage:** https://erc8004.agency/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-nirholas-bnb-chain-toolkit
- Seller: https://agentstack.voostack.com/s/nirholas
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.