Skip to content

faq.md

Latest commit

 

History

History
345 lines (225 loc) · 11.3 KB

faq.md

File metadata and controls

345 lines (225 loc) · 11.3 KB

Frequently Asked Questions

Honest answers to common questions about the BNB Chain AI Toolkit.

Don't know a term? Check the Glossary. Having a technical problem? See Troubleshooting.

General

What is this project?

BNB Chain AI Toolkit is an open-source collection of AI agents, MCP servers, market data tools, DeFi utilities, wallet tools, and Web3 standards — all focused on the BNB Chain ecosystem.

In simplest terms: it gives AI assistants (like Claude, ChatGPT) the ability to interact with blockchains, trade on exchanges, and analyze crypto data — instead of just talking about crypto.

For a full non-technical explanation, see What Is This?.

Do I need to know how to code?

It depends on what you want to do:

Goal Coding Required?
Use pre-built agents in Claude/ChatGPT No — just copy-paste the system prompt
Start an MCP server Minimal — you need to run a few terminal commands
Fetch market data in your app Yes — basic TypeScript/JavaScript
Create custom agents No — just edit JSON files
Extend MCP servers Yes — TypeScript knowledge
Deploy smart contracts Yes — Solidity knowledge

The Getting Started guide walks through everything step by step.

Is this free?

Yes. The entire toolkit is open source under the MIT license. You can use, modify, and distribute it freely — including for commercial purposes.

Some external services have their own pricing:

  • CoinGecko API — Free tier (30 calls/min), Pro for higher limits
  • Binance API — Free, but exchange trading has trading fees
  • RPC endpoints — Free public nodes included, paid nodes for higher reliability
What's the difference between agents, MCP servers, and tools?

This is the most important distinction:

Component What It Is Analogy
Agent A personality/expertise definition (JSON text) A job description for an expert
MCP Server A running program that connects AI to external data The phone and computer the expert uses
Tool A single action an MCP server can perform One button on a remote control

They work together: You load an agent (expertise) into Claude, connect an MCP server (tools), and the agent uses the tools to answer your questions with real data.

They also work independently: You can use agents without MCP servers (for theoretical/educational advice) or MCP servers without agents (Claude uses its built-in knowledge to call tools).

Is this free?

Yes. The entire toolkit is open source under the MIT license. You can use, modify, and distribute it freely.

Some external services (like CoinGecko Pro API or Binance exchange) may have their own pricing.

Which AI assistants does this work with?
Assistant MCP Support Agent Support
Claude Desktop ✅ ✅
Claude Code ✅ ✅
ChatGPT ❌ (use API) ✅
GitHub Copilot ✅ ✅
Cursor ✅ ✅
Any LLM API Via wrapper ✅
Which blockchains are supported?

Primary focus: BNB Smart Chain (BSC), opBNB, BNB Greenfield

Also supported: networks including Ethereum, Polygon, Arbitrum, Base, Optimism, Avalanche, Solana, and many more.

See the full list in the Architecture guide.

Security

Is it safe to use?

The toolkit itself is open source and auditable. However, anything involving private keys or real money carries inherent risk.

Safety guidelines:

  • Never share your private keys
  • Start with testnet
  • Start with small amounts
  • Review transactions before confirming
  • Use read-only API keys when possible
Does this store my private keys?

No. Private keys are provided via environment variables and never stored, logged, or transmitted by the toolkit. They stay in your local environment.

Has the code been audited?

Not yet. This is an open-source project and the code is available for anyone to review. We welcome security researchers to examine the codebase.

If you find a vulnerability, please follow the Security Policy.

Technical

What are MCP servers?

MCP (Model Context Protocol) servers are bridges between AI assistants and external services. They expose "tools" that AI can call — like checking a wallet balance, placing a trade, or fetching news.

Think of them as APIs specifically designed for AI consumption.

Learn more: MCP Servers Guide.

What's the difference between agents and MCP servers?
Agents MCP Servers
What Personality/expertise definitions Live services with tools
Format JSON files Running processes
Purpose Tell AI how to think about crypto Let AI do things on-chain
Needs internet? No Yes
Example "You are a PancakeSwap expert" getTokenBalance("BNB")

They work best together — agents provide the domain knowledge, MCP servers provide the tools.

Can I use this without BNB Chain?

Yes! While the toolkit focuses on BNB Chain, many components support other networks:

  • Universal Crypto MCP supports chains
  • Agenti supports all EVM chains + Solana
  • Market data works for all listed cryptocurrencies
  • DeFi agents work cross-chain
  • Wallet toolkit works with any EVM chain
What Node.js version do I need?

Node.js 18 or higher. We recommend using the latest LTS version.

Check your version: node --version

Can I use npm instead of bun?

Yes. Replace bun install with npm install and bun start with npm start. Everything works the same.

Troubleshooting

bun install fails
  1. Make sure bun is installed: bun --version
  2. If not: curl -fsSL https://bun.sh/install | bash
  3. Try deleting node_modules and re-running: rm -rf node_modules && bun install
MCP server won't start
  1. Check that you're in the right directory: cd mcp-servers/<server-name>
  2. Run bun install first
  3. Check environment variables are set
  4. Check Node.js version: node --version (need 18+)
  5. See Troubleshooting for more
Claude doesn't see the MCP tools
  1. Make sure the server is running before opening Claude
  2. Check your claude_desktop_config.json for typos (use jq . config.json to validate JSON)
  3. Fully restart Claude Desktop (Cmd+Q / right-click tray → Quit, then reopen)
  4. Check Claude Desktop logs for errors

Config file locations:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

More troubleshooting? See the full Troubleshooting guide for step-by-step diagnosis of every known issue.

Concepts

What is BNB Chain?

BNB Chain is a family of blockchains built by Binance (one of the world's largest crypto exchanges). It includes:

  • BNB Smart Chain (BSC) — The main chain for apps and DeFi (fast, cheap fees)
  • opBNB — A Layer 2 that makes BSC even faster
  • BNB Greenfield — A chain for decentralized file storage

This toolkit primarily targets these networks but supports others.

See the Glossary for detailed definitions of these terms.

What is DeFi?

DeFi (Decentralized Finance) = financial services built on blockchains instead of traditional banks. Trading, lending, borrowing, earning interest — all run by smart contracts (automated programs) instead of companies.

The toolkit's agents specialize in different DeFi activities. See the Glossary for a full breakdown.

Can the AI lose my money?

Not by itself. The toolkit has several safety layers:

  1. Write operations require confirmation — Claude asks before sending transactions
  2. Dry run by default — Tools like the Dust Sweeper preview actions without executing
  3. No stored secrets — Private keys stay in your local environment variables
  4. Testnet support — Practice with fake money first

However, crypto carries inherent risks (market volatility, smart contract bugs, user error). Always start with small amounts and understand what you're authorizing.

How is this different from other crypto AI tools?
Feature This Toolkit Most Others
Open source ✅ Often closed
Number of agents 78 1-5
MCP servers 6 0-1
Multi-chain support 1-3
Agent definitions as JSON ✅ Proprietary format
On-chain agent identity (ERC-8004) ✅ ❌
Accessibility standard (W3AG) ✅ ❌
30+ language translations ✅ ❌

The toolkit is unusually comprehensive. Most crypto AI tools solve one problem; this one aims to cover the entire BNB Chain stack.

Contributing

How can I contribute?

Many ways, no matter your skill level:

Skill Level How To Contribute
Anyone Star the repo, report bugs, suggest features
Writer Improve docs, fix typos, add translations
Beginner dev Add new agents (just JSON editing)
Intermediate dev Add market data sources, write tests
Advanced dev Extend MCP servers, add chain support
Researcher Improve ERC-8004 or W3AG standards

See CONTRIBUTING.md for full details.

Can I add my own agents?

Absolutely! It takes about 5 minutes. See the Agents Guide for step-by-step instructions.

The short version:

  1. Copy agents/bnb-chain-agents/agent-template.json
  2. Edit the fields (identifier, title, systemRole)
  3. Run bun run build
  4. Your agent is now in the index
Can I use this in my own product?

Yes. The MIT license allows commercial use, modification, and redistribution. Attribution is appreciated but not legally required.

See Also