Skip to content

API Reference

Comprehensive API documentation for BNB-Chain-MCP Server.

Overview

BNB-Chain-MCP provides 120+ tools across multiple categories for interacting with EVM-compatible blockchains. The server supports three transport modes and integrates with Claude Desktop, Cursor, ChatGPT, and custom MCP clients.

Server Modes

Mode Command Port Use Case
stdio npx @nirholas/bnb-chain-mcp N/A Claude Desktop, Cursor
HTTP npx @nirholas/bnb-chain-mcp --http 3001 ChatGPT Developer Mode
SSE npx @nirholas/bnb-chain-mcp --sse 3001 Legacy HTTP clients

Supported Networks

Network Chain ID Native Token
Ethereum 1 ETH
BNB Smart Chain 56 BNB
Arbitrum One 42161 ETH
Polygon 137 MATIC
Base 8453 ETH
Optimism 10 ETH
opBNB 204 BNB
+ Testnets Various Various

Quick Reference

Tool Categories

Category Tools Description
Network 12 Chain info, RPC endpoints, network status
Blocks 10 Block queries, block range, miner info
Transactions 14 Send, trace, simulate, batch transactions
Wallet 15 Create wallet, balances, approvals, HD derivation
Tokens 18 ERC-20 operations, transfers, permits
NFT 12 ERC-721/1155, metadata, transfers
Swap 8 DEX swaps, quotes, liquidity, aggregation
Bridge 6 Cross-chain transfers, bridge quotes
Staking 8 Native staking, liquid staking, farming
Lending 10 Aave/Compound, supply, borrow, flash loans
Price Feeds 6 Chainlink oracles, TWAP, price aggregation
Gas 6 Gas prices, EIP-1559, estimation
Events 5 Historical logs, event filtering, decoding
Multicall 3 Batch read/write operations
Signatures 5 Sign/verify messages, EIP-712
Domains 8 ENS registration, resolution, records
Security 12 Honeypot detection, rug checks, GoPlus
Portfolio 4 Track holdings across chains
Governance 9 Proposals, voting, delegation
Contracts 8 Read/write, ABI encoding, verification
Deployment 5 Deploy, CREATE2, proxies
MEV 6 Flashbots, private transactions
Market Data 15 CoinGecko, CoinStats, prices, OHLCV
DeFi Analytics 12 DefiLlama TVL, yields, protocols
DEX Analytics 10 Pool data, trades, trending tokens
Social 8 LunarCrush sentiment, influencers
News 7 Crypto news aggregation

Authentication

Environment Variables

# Required for write operations
PRIVATE_KEY=0x...your_private_key

# Optional API keys (enhance functionality)
COINGECKO_API_KEY=your_key      # Higher rate limits
COINSTATS_API_KEY=your_key      # Portfolio tracking
LUNARCRUSH_API_KEY=your_key     # Social sentiment
CRYPTOPANIC_API_KEY=your_key    # News aggregation

Security Best Practices

Private Key Security

  • Never commit private keys to version control
  • Use environment variables or secure vaults
  • Consider using separate keys for testing
  • Monitor wallets for unauthorized transactions

Common Parameters

Many tools share common parameters:

Network Selection

network: z.enum([
  "ethereum", "bsc", "arbitrum", "polygon", 
  "base", "optimism", "opbnb", "sepolia",
  "bsc-testnet", "arbitrum-sepolia"
]).default("ethereum")

Address Validation

address: z.string()
  .regex(/^0x[a-fA-F0-9]{40}$/)
  .describe("Valid Ethereum address")

Amount Formatting

amount: z.string()
  .describe("Amount in human-readable format (e.g., '1.5' ETH)")

Response Format

All tools return responses in a consistent format:

Success Response

{
  "content": [
    {
      "type": "text",
      "text": "{\n  \"result\": ...\n}"
    }
  ]
}

Error Response

{
  "content": [
    {
      "type": "text", 
      "text": "Error: Insufficient balance for transfer"
    }
  ],
  "isError": true
}

Rate Limits

Default Limits

Provider Free Tier With API Key
CoinGecko 10-30 req/min 500 req/min
CoinStats 100 req/day 10,000 req/day
LunarCrush 10 req/min 1,000 req/min
DefiLlama Unlimited N/A
GoPlus 100 req/min N/A

RPC Rate Limits

RPC endpoints have varying rate limits. Consider using:

  • Alchemy or Infura for production
  • QuickNode for high-throughput applications
  • Chainlist for finding public RPCs

Next Steps

API Versioning

Current version: 1.0.0

The API follows semantic versioning:

  • Major: Breaking changes
  • Minor: New features, backward compatible
  • Patch: Bug fixes

Breaking changes are documented in the CHANGELOG.