# BNB Chain MCP - Complete Reference
> Comprehensive documentation for the BNB Chain MCP Server - enabling AI agents to interact with BNB Chain and EVM-compatible blockchains.
---
## Table of Contents
1. [Project Overview](#1-project-overview)
2. [Installation & Configuration](#2-installation--configuration)
3. [Supported Networks](#3-supported-networks)
4. [Complete Tool Reference](#4-complete-tool-reference)
5. [Data Provider Integrations](#5-data-provider-integrations)
6. [Environment Variables](#6-environment-variables)
7. [Server Modes](#7-server-modes)
8. [Error Handling](#8-error-handling)
9. [Examples & Use Cases](#9-examples--use-cases)
---
## 1. Project Overview
### Description
BNB Chain MCP is a TypeScript-based Model Context Protocol (MCP) server that enables AI agents to interact with BNB Chain and EVM-compatible blockchains through natural language commands. Built on the MCP SDK, it provides a standardized interface for blockchain operations, market data, security analysis, and DeFi interactions.
### Target Users
- **AI Agents**: Claude, ChatGPT, and other LLM-powered assistants
- **Developers**: Building blockchain-aware AI applications
- **Traders**: Automated analysis and execution
- **Researchers**: On-chain data analysis and monitoring
### Key Features
- 🔄 **175+ Tools** across 22 functional categories
- 🌐 **8+ Networks** supported (mainnets + testnets)
- 🔒 **Security-First** with GoPlus integration
- 📊 **Rich Analytics** via DefiLlama, CoinGecko, LunarCrush
- ⚡ **Multiple Transport Modes** (stdio, HTTP, SSE)
### Architecture
```
┌─────────────────────────────────────────────────────────┐
│ MCP Server │
├─────────────────────────────────────────────────────────┤
│ Transport Layer (stdio / HTTP / SSE) │
├─────────────────────────────────────────────────────────┤
│ Tool Registration & Routing │
├──────────────┬──────────────┬──────────────┬───────────┤
│ EVM Modules │ Data Modules │ Analytics │ Utilities │
│ - Network │ - News │ - Market │ - Logger │
│ - Tokens │ - Social │ - DeFi │ - Helper │
│ - Swap │ - Governance │ - DEX │ │
│ - Bridge │ │ │ │
│ - Security │ │ │ │
│ - Staking │ │ │ │
│ - Lending │ │ │ │
│ - NFT │ │ │ │
│ - ... │ │ │ │
├──────────────┴──────────────┴──────────────┴───────────┤
│ viem (Ethereum Client) + External APIs │
└─────────────────────────────────────────────────────────┘
```
---
## 2. Installation & Configuration
### NPX (Recommended)
```bash
npx @nirholas/bnb-chain-mcp@latest
```
### Local Development
```bash
git clone https://github.com/nirholas/bnb-chain-mcp
cd bnb-chain-mcp
bun install
bun dev # stdio mode
bun dev:http # HTTP mode
bun dev:sse # SSE mode
```
### Claude Desktop Configuration
Add to `claude_desktop_config.json`:
```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"
}
}
}
}
```
### Cursor Configuration
Add to MCP settings:
```json
{
"mcpServers": {
"bnb-chain-mcp": {
"command": "npx",
"args": ["-y", "@nirholas/bnb-chain-mcp@latest"],
"env": {
"PRIVATE_KEY": "0x..."
}
}
}
}
```
### ChatGPT Developer Mode
1. Enable Developer Mode in ChatGPT settings
2. Start HTTP server: `npx @nirholas/bnb-chain-mcp@latest --http`
3. Add app URL in ChatGPT: `http://localhost:3001/mcp`
---
## 3. Supported Networks
### Mainnets
| Network | Chain ID | Native Token | RPC Default |
|---------|----------|--------------|-------------|
| Ethereum | 1 | ETH | eth.llamarpc.com |
| BNB Smart Chain | 56 | BNB | bsc-dataseed.binance.org |
| Arbitrum One | 42161 | ETH | arb1.arbitrum.io/rpc |
| Polygon | 137 | MATIC | polygon-rpc.com |
| Base | 8453 | ETH | mainnet.base.org |
| Optimism | 10 | ETH | mainnet.optimism.io |
| opBNB | 204 | BNB | opbnb-mainnet-rpc.bnbchain.org |
| IoTeX | 4689 | IOTX | babel-api.mainnet.iotex.io |
### Testnets
| Network | Chain ID | Mainnet Equivalent |
|---------|----------|-------------------|
| Sepolia | 11155111 | Ethereum |
| BSC Testnet | 97 | BNB Smart Chain |
| Arbitrum Sepolia | 421614 | Arbitrum One |
| Base Sepolia | 84532 | Base |
| Polygon Amoy | 80002 | Polygon |
| Optimism Sepolia | 11155420 | Optimism |
| opBNB Testnet | 5611 | opBNB |
| IoTeX Testnet | 4690 | IoTeX |
### Network Aliases
You can use friendly names instead of chain IDs:
- `ethereum`, `mainnet`, `eth` → Chain ID 1
- `bsc`, `binance` → Chain ID 56
- `arbitrum`, `arb` → Chain ID 42161
- `polygon`, `matic` → Chain ID 137
- `base` → Chain ID 8453
- `optimism`, `op` → Chain ID 10
---
## 4. Complete Tool Reference
### 4.1 Network Module (8 tools)
#### `get_chain_info`
Get chain information for a specific network.
- **Parameters:**
- `network` (string, optional): Network name or chain ID. Default: "ethereum"
- **Returns:** Chain ID, name, native currency, block explorer, RPC URL
#### `get_supported_networks`
Get list of all supported networks with metadata.
- **Parameters:** None
- **Returns:** Array of network objects with chain ID, name, aliases
#### `estimate_block_time`
Estimate average block time for a network.
- **Parameters:**
- `network` (string, optional): Network identifier
- `sampleSize` (number, optional): Blocks to sample. Default: 100
- **Returns:** Average block time in seconds
#### `get_finality_status`
Get finality status for a block or transaction.
- **Parameters:**
- `network` (string, optional): Network identifier
- `blockNumber` (number, optional): Block to check
- `txHash` (string, optional): Transaction hash
- **Returns:** Finality status, confirmations, safe/finalized flags
#### `get_pending_transactions_info`
Get mempool information and pending transaction count.
- **Parameters:**
- `network` (string, optional): Network identifier
- **Returns:** Pending count, gas price trends
#### `get_network_metadata`
Get comprehensive network metadata.
- **Parameters:**
- `network` (string, optional): Network identifier
- **Returns:** Full chain config, explorers, contracts, tokens
#### `get_gas_oracle`
Get comprehensive gas price recommendations.
- **Parameters:**
- `network` (string, optional): Network identifier
- **Returns:** Safe/standard/fast gas prices, base fee, priority fees
#### `get_network_health`
Check network synchronization and health status.
- **Parameters:**
- `network` (string, optional): Network identifier
- **Returns:** Sync status, block height, peer count
---
### 4.2 Blocks Module (9 tools)
#### `get_block_by_hash`
Get a block by its hash.
- **Parameters:**
- `network` (string, optional): Network identifier
- `blockHash` (string): Block hash (0x...)
- `includeTransactions` (boolean, optional): Include full tx data
- **Returns:** Block object with header and transactions
#### `get_block_by_number`
Get a block by number.
- **Parameters:**
- `network` (string, optional): Network identifier
- `blockNumber` (number): Block number
- `includeTransactions` (boolean, optional): Include full tx data
- **Returns:** Block object
#### `get_latest_block`
Get the most recent block.
- **Parameters:**
- `network` (string, optional): Network identifier
- **Returns:** Latest block with full details
#### `get_block_with_transactions`
Get block with full transaction details.
- **Parameters:**
- `network` (string, optional): Network identifier
- `blockNumber` (number): Block number
- **Returns:** Block with expanded transaction objects
#### `get_uncle_blocks`
Get uncle/ommer blocks for a specific block.
- **Parameters:**
- `network` (string, optional): Network identifier
- `blockNumber` (number): Block number
- **Returns:** Array of uncle block headers
#### `get_block_receipts`
Get all transaction receipts for a block.
- **Parameters:**
- `network` (string, optional): Network identifier
- `blockNumber` (number): Block number
- **Returns:** Array of transaction receipts with logs
#### `get_block_range`
Get summary information for a range of blocks.
- **Parameters:**
- `network` (string, optional): Network identifier
- `startBlock` (number): Start block number
- `endBlock` (number): End block number
- **Returns:** Array of block summaries
#### `get_block_rewards`
Estimate block rewards for miners/validators.
- **Parameters:**
- `network` (string, optional): Network identifier
- `blockNumber` (number): Block number
- **Returns:** Base reward, transaction fees, total reward
#### `get_blocks_by_miner`
Find recent blocks produced by a specific miner/validator.
- **Parameters:**
- `network` (string, optional): Network identifier
- `minerAddress` (string): Miner/validator address
- `limit` (number, optional): Max blocks to return. Default: 10
- **Returns:** Array of blocks produced by the address
---
### 4.3 Transactions Module (6 tools)
#### `get_transaction`
Get detailed information about a transaction.
- **Parameters:**
- `network` (string, optional): Network identifier
- `txHash` (string): Transaction hash
- **Returns:** Full transaction details including receipt
#### `estimate_gas`
Estimate gas cost for a transaction.
- **Parameters:**
- `network` (string, optional): Network identifier
- `to` (string): Recipient address
- `value` (string, optional): Value in wei
- `data` (string, optional): Call data
- **Returns:** Estimated gas units
#### `speed_up_transaction`
Speed up a pending transaction with higher gas.
- **Parameters:**
- `network` (string, optional): Network identifier
- `txHash` (string): Original transaction hash
- `privateKey` (string): Wallet private key
- `gasPriceMultiplier` (number, optional): Multiplier. Default: 1.5
- **Returns:** New transaction hash
#### `cancel_transaction`
Cancel a pending transaction.
- **Parameters:**
- `network` (string, optional): Network identifier
- `nonce` (number): Transaction nonce to cancel
- `privateKey` (string): Wallet private key
- **Returns:** Cancellation transaction hash
#### `get_pending_transaction_count`
Get count of pending transactions for an address.
- **Parameters:**
- `network` (string, optional): Network identifier
- `address` (string): Wallet address
- **Returns:** Pending nonce vs confirmed nonce
#### `simulate_transaction`
Simulate transaction execution.
- **Parameters:**
- `network` (string, optional): Network identifier
- `to` (string): Recipient address
- `value` (string, optional): Value in wei
- `data` (string, optional): Call data
- `from` (string, optional): Sender address
- **Returns:** Simulation result, gas used, return data
---
### 4.4 Tokens Module (14 tools)
#### `get_erc20_token_info`
Get ERC20 token information.
- **Parameters:**
- `tokenAddress` (string): Token contract address
- `network` (string, optional): Network identifier
- **Returns:** Name, symbol, decimals, total supply
#### `get_native_balance`
Get native token balance for an address.
- **Parameters:**
- `network` (string, optional): Network identifier
- `address` (string, optional): Address to check
- `privateKey` (string, optional): Derive address from key
- **Returns:** Balance in native units and wei
#### `get_erc20_balance`
Get ERC20 token balance.
- **Parameters:**
- `tokenAddress` (string): Token contract address
- `address` (string): Address to check
- `network` (string, optional): Network identifier
- **Returns:** Balance with token info
#### `create_erc20_token`
Deploy a new ERC20 token.
- **Parameters:**
- `name` (string): Token name
- `symbol` (string): Token symbol
- `network` (string, optional): Network identifier
- `privateKey` (string): Deployer private key
- **Returns:** Deployed token address, transaction hash
#### `wrap_native_token`
Wrap native tokens (ETH→WETH, BNB→WBNB).
- **Parameters:**
- `amount` (string): Amount to wrap (e.g., "1.5")
- `privateKey` (string): Wallet private key
- `network` (string, optional): Network identifier
- **Returns:** Transaction hash, wrapped token address
#### `unwrap_native_token`
Unwrap wrapped tokens (WETH→ETH, WBNB→BNB).
- **Parameters:**
- `amount` (string): Amount to unwrap
- `privateKey` (string): Wallet private key
- `network` (string, optional): Network identifier
- **Returns:** Transaction hash
#### `get_wrapped_native_balance`
Get wrapped native token balance.
- **Parameters:**
- `address` (string): Address to check
- `network` (string, optional): Network identifier
- **Returns:** WETH/WBNB/WMATIC balance
#### `batch_transfer_erc20`
Transfer tokens to multiple recipients.
- **Parameters:**
- `tokenAddress` (string): Token contract address
- `recipients` (array): [{address, amount}] pairs
- `privateKey` (string): Wallet private key
- `network` (string, optional): Network identifier
- **Returns:** Array of transaction results
#### `burn_erc20_tokens`
Burn ERC20 tokens.
- **Parameters:**
- `tokenAddress` (string): Token contract address
- `amount` (string): Amount to burn
- `privateKey` (string): Wallet private key
- `network` (string, optional): Network identifier
- **Returns:** Burn transaction hash
#### `get_token_holder_count`
Estimate token holder count from events.
- **Parameters:**
- `tokenAddress` (string): Token contract address
- `network` (string, optional): Network identifier
- **Returns:** Estimated holder count
#### `check_token_allowance`
Check ERC20 allowance for a spender.
- **Parameters:**
- `tokenAddress` (string): Token contract address
- `owner` (string): Token owner address
- `spender` (string): Spender address
- `network` (string, optional): Network identifier
- **Returns:** Allowance amount
#### `approve_token_spending`
Approve spender to use tokens.
- **Parameters:**
- `tokenAddress` (string): Token contract address
- `spender` (string): Spender address
- `amount` (string): Amount to approve
- `privateKey` (string): Wallet private key
- `network` (string, optional): Network identifier
- **Returns:** Approval transaction hash
#### `revoke_token_approval`
Revoke token spending approval.
- **Parameters:**
- `tokenAddress` (string): Token contract address
- `spender` (string): Spender address
- `privateKey` (string): Wallet private key
- `network` (string, optional): Network identifier
- **Returns:** Revocation transaction hash
#### `get_token_supply_info`
Get comprehensive token supply info.
- **Parameters:**
- `tokenAddress` (string): Token contract address
- `network` (string, optional): Network identifier
- **Returns:** Total, burned, circulating supply
---
### 4.5 Wallet Module (13 tools)
#### `get_address_from_private_key`
Derive EVM address from private key.
- **Parameters:**
- `privateKey` (string): Private key (0x...)
- **Returns:** Derived address
#### `generate_mnemonic`
Generate BIP-39 mnemonic phrase.
- **Parameters:**
- `wordCount` (number, optional): 12 or 24. Default: 12
- **Returns:** Mnemonic phrase
#### `derive_addresses_from_mnemonic`
Derive multiple addresses from mnemonic.
- **Parameters:**
- `mnemonic` (string): BIP-39 mnemonic
- `count` (number, optional): Addresses to derive. Default: 5
- `startIndex` (number, optional): Starting index. Default: 0
- **Returns:** Array of address/path pairs
#### `create_wallet`
Create a new random wallet.
- **Parameters:** None
- **Returns:** Address, private key, mnemonic
#### `import_wallet_from_mnemonic`
Import wallet from mnemonic.
- **Parameters:**
- `mnemonic` (string): BIP-39 mnemonic
- `index` (number, optional): Derivation index. Default: 0
- **Returns:** Address, private key
#### `transfer_native_token`
Transfer native tokens (ETH, BNB, MATIC).
- **Parameters:**
- `to` (string): Recipient address
- `amount` (string): Amount in native units
- `privateKey` (string): Wallet private key
- `network` (string, optional): Network identifier
- **Returns:** Transaction hash
#### `approve_token_spending`
Approve ERC20 spending.
- **Parameters:**
- `tokenAddress` (string): Token contract
- `spender` (string): Spender address
- `amount` (string): Amount to approve
- `privateKey` (string): Wallet private key
- `network` (string, optional): Network identifier
- **Returns:** Approval transaction hash
#### `transfer_erc20`
Transfer ERC20 tokens.
- **Parameters:**
- `tokenAddress` (string): Token contract
- `to` (string): Recipient address
- `amount` (string): Amount to transfer
- `privateKey` (string): Wallet private key
- `network` (string, optional): Network identifier
- **Returns:** Transaction hash
#### `get_token_approvals`
Get list of token approvals.
- **Parameters:**
- `address` (string): Wallet address
- `tokenAddresses` (array): Tokens to check
- `network` (string, optional): Network identifier
- **Returns:** Array of approval details
#### `revoke_token_approval`
Revoke token approval.
- **Parameters:**
- `tokenAddress` (string): Token contract
- `spender` (string): Spender to revoke
- `privateKey` (string): Wallet private key
- `network` (string, optional): Network identifier
- **Returns:** Revocation transaction hash
#### `sign_message`
Sign a message with private key.
- **Parameters:**
- `message` (string): Message to sign
- `privateKey` (string): Wallet private key
- **Returns:** Signature
#### `verify_message`
Verify signed message and recover signer.
- **Parameters:**
- `message` (string): Original message
- `signature` (string): Signature to verify
- **Returns:** Recovered signer address
#### `get_wallet_portfolio`
Get comprehensive portfolio summary.
- **Parameters:**
- `address` (string): Wallet address
- `network` (string, optional): Network identifier
- **Returns:** Native balance, token balances, total value
---
### 4.6 Swap Module (12 tools)
#### `get_swap_quote`
Get swap quote for token exchange.
- **Parameters:**
- `tokenIn` (string): Token to sell address
- `tokenOut` (string): Token to buy address
- `amountIn` (string): Input amount in wei
- `network` (string, optional): Network identifier
- `dex` (string, optional): Specific DEX (uniswap, pancakeswap)
- **Returns:** Expected output, price impact, router address
#### `execute_swap`
Execute a token swap.
- **Parameters:**
- `tokenIn` (string): Token to sell
- `tokenOut` (string): Token to buy
- `amountIn` (string): Input amount in wei
- `minAmountOut` (string): Minimum output (slippage protection)
- `network` (string, optional): Network identifier
- `privateKey` (string): Wallet private key
- `dex` (string, optional): Specific DEX
- `deadline` (number, optional): Deadline in seconds. Default: 1200
- **Returns:** Transaction hash, amounts swapped
#### `get_best_route`
Find optimal swap route across DEXs.
- **Parameters:**
- `tokenIn` (string): Token to sell
- `tokenOut` (string): Token to buy
- `amountIn` (string): Input amount
- `network` (string, optional): Network identifier
- **Returns:** Best route with amounts from each DEX
#### `get_dex_liquidity`
Get liquidity for a trading pair.
- **Parameters:**
- `tokenA` (string): First token address
- `tokenB` (string): Second token address
- `network` (string, optional): Network identifier
- `dex` (string, optional): Specific DEX
- **Returns:** Pool reserves, liquidity depth
#### `get_price_impact`
Calculate price impact for trade size.
- **Parameters:**
- `tokenIn` (string): Token to sell
- `tokenOut` (string): Token to buy
- `amountIn` (string): Trade size in wei
- `network` (string, optional): Network identifier
- **Returns:** Price impact percentage
#### `get_supported_dexs`
List supported DEXs on a network.
- **Parameters:**
- `network` (string, optional): Network identifier
- **Returns:** Array of DEX names and router addresses
#### `add_liquidity`
Add liquidity to a DEX pair.
- **Parameters:**
- `tokenA` (string): First token address
- `tokenB` (string): Second token address
- `amountA` (string): Amount of token A
- `amountB` (string): Amount of token B
- `privateKey` (string): Wallet private key
- `network` (string, optional): Network identifier
- `dex` (string, optional): Specific DEX
- **Returns:** Transaction hash, LP tokens received
#### `add_liquidity_native`
Add liquidity with native token.
- **Parameters:**
- `token` (string): Token address to pair with native
- `amountToken` (string): Token amount
- `amountNative` (string): Native token amount
- `privateKey` (string): Wallet private key
- `network` (string, optional): Network identifier
- **Returns:** Transaction hash, LP tokens received
#### `remove_liquidity`
Remove liquidity from a DEX pair.
- **Parameters:**
- `tokenA` (string): First token address
- `tokenB` (string): Second token address
- `liquidity` (string): LP tokens to burn
- `privateKey` (string): Wallet private key
- `network` (string, optional): Network identifier
- `dex` (string, optional): Specific DEX
- **Returns:** Transaction hash, tokens received
#### `get_lp_balance`
Get LP token balance.
- **Parameters:**
- `tokenA` (string): First token address
- `tokenB` (string): Second token address
- `address` (string): Wallet address
- `network` (string, optional): Network identifier
- **Returns:** LP balance, share of pool
#### `get_pool_reserves`
Get pool reserves.
- **Parameters:**
- `tokenA` (string): First token address
- `tokenB` (string): Second token address
- `network` (string, optional): Network identifier
- **Returns:** Reserve0, reserve1, total supply
#### `calculate_arbitrage`
Calculate arbitrage opportunity.
- **Parameters:**
- `tokenA` (string): First token
- `tokenB` (string): Second token
- `amount` (string): Trade amount
- `network` (string, optional): Network identifier
- **Returns:** Arbitrage profit potential across DEXs
---
### 4.7 Security Module (20 tools)
#### `analyze_token_security`
Analyze token for security risks.
- **Parameters:**
- `tokenAddress` (string): Token contract address
- `network` (string, optional): Network identifier
- **Returns:** Risk score, risk level, detected issues
#### `check_approval_risks`
Check wallet approvals for risks.
- **Parameters:**
- `walletAddress` (string): Wallet to check
- `tokenAddresses` (array, optional): Specific tokens
- `network` (string, optional): Network identifier
- **Returns:** Risky unlimited approvals
#### `verify_contract`
Check contract verification status.
- **Parameters:**
- `contractAddress` (string): Contract address
- `network` (string, optional): Network identifier
- **Returns:** Verification status, code size, proxy detection
#### `simulate_transaction`
Simulate transaction for safety.
- **Parameters:**
- `to` (string): Target address
- `value` (string, optional): Value in wei
- `data` (string, optional): Call data
- `network` (string, optional): Network identifier
- **Returns:** Simulation result, warnings
#### `check_address_type`
Determine address type (EOA, contract, known entity).
- **Parameters:**
- `address` (string): Address to check
- `network` (string, optional): Network identifier
- **Returns:** Address type classification
#### `decode_transaction_data`
Decode transaction input data.
- **Parameters:**
- `data` (string): Transaction input data
- `abi` (array, optional): Contract ABI
- **Returns:** Decoded function call
#### `detect_rug_pull_risk`
Analyze token for rug pull indicators.
- **Parameters:**
- `tokenAddress` (string): Token to analyze
- `network` (string, optional): Network identifier
- **Returns:** Risk indicators (hidden mint, honeypot, etc.)
#### `get_holder_distribution`
Analyze token holder distribution.
- **Parameters:**
- `tokenAddress` (string): Token address
- `network` (string, optional): Network identifier
- **Returns:** Top holders, concentration metrics
#### `check_contract_ownership`
Verify contract ownership status.
- **Parameters:**
- `contractAddress` (string): Contract address
- `network` (string, optional): Network identifier
- **Returns:** Owner address, renounced status
#### `detect_honeypot`
Check if token is a honeypot.
- **Parameters:**
- `tokenAddress` (string): Token address
- `network` (string, optional): Network identifier
- **Returns:** Honeypot status, buy/sell taxes
#### `analyze_contract_permissions`
Analyze contract for dangerous permissions.
- **Parameters:**
- `contractAddress` (string): Contract address
- `network` (string, optional): Network identifier
- **Returns:** Dangerous functions detected
#### `verify_contract_source`
Check source verification on explorers.
- **Parameters:**
- `contractAddress` (string): Contract address
- `network` (string, optional): Network identifier
- **Returns:** Verification status per explorer
#### `goplus_token_security`
GoPlus token security analysis.
- **Parameters:**
- `tokenAddress` (string): Token address
- `chainId` (number, optional): Chain ID
- **Returns:** Comprehensive GoPlus security report
#### `goplus_address_security`
GoPlus address security check.
- **Parameters:**
- `address` (string): Address to check
- **Returns:** Malicious activity associations
#### `goplus_approval_security`
GoPlus approval security analysis.
- **Parameters:**
- `tokenAddress` (string): Token address
- `ownerAddress` (string): Owner address
- `chainId` (number, optional): Chain ID
- **Returns:** Approval security assessment
#### `goplus_nft_security`
GoPlus NFT collection security.
- **Parameters:**
- `contractAddress` (string): NFT contract
- `chainId` (number, optional): Chain ID
- **Returns:** NFT security analysis
#### `goplus_dapp_security`
GoPlus dApp/website security.
- **Parameters:**
- `url` (string): dApp URL
- **Returns:** Phishing detection results
#### `goplus_signature_decode`
GoPlus signature/permit decode.
- **Parameters:**
- `data` (string): Signature data
- **Returns:** Decoded signature explanation
#### `goplus_supported_chains`
Get GoPlus supported chains.
- **Parameters:** None
- **Returns:** List of supported chain IDs
#### `goplus_rugpull_detection`
Comprehensive GoPlus rug pull detection.
- **Parameters:**
- `tokenAddress` (string): Token address
- `chainId` (number, optional): Chain ID
- **Returns:** Rug pull risk assessment
---
### 4.8 Staking Module (14 tools)
#### `get_staking_position`
Get staking position and rewards.
- **Parameters:**
- `stakingContract` (string): Staking contract address
- `address` (string): User address
- `network` (string, optional): Network identifier
- **Returns:** Staked amount, pending rewards
#### `stake_tokens`
Stake tokens in a staking contract.
- **Parameters:**
- `stakingContract` (string): Staking contract
- `amount` (string): Amount to stake
- `privateKey` (string): Wallet private key
- `network` (string, optional): Network identifier
- **Returns:** Stake transaction hash
#### `unstake_tokens`
Unstake/withdraw tokens.
- **Parameters:**
- `stakingContract` (string): Staking contract
- `amount` (string): Amount to unstake
- `privateKey` (string): Wallet private key
- `network` (string, optional): Network identifier
- **Returns:** Unstake transaction hash
#### `claim_staking_rewards`
Claim pending staking rewards.
- **Parameters:**
- `stakingContract` (string): Staking contract
- `privateKey` (string): Wallet private key
- `network` (string, optional): Network identifier
- **Returns:** Claim transaction hash, rewards amount
#### `get_staking_apr`
Calculate staking APR.
- **Parameters:**
- `stakingContract` (string): Staking contract
- `network` (string, optional): Network identifier
- **Returns:** Estimated APR percentage
#### `get_staking_protocols`
List popular staking protocols.
- **Parameters:**
- `network` (string, optional): Network identifier
- **Returns:** Protocol addresses and APRs
#### `stake_eth_lido`
Stake ETH with Lido for stETH.
- **Parameters:**
- `amount` (string): ETH amount
- `privateKey` (string): Wallet private key
- `network` (string, optional): Network (ethereum)
- **Returns:** Transaction hash, stETH received
#### `wrap_steth`
Wrap stETH to wstETH.
- **Parameters:**
- `amount` (string): stETH amount
- `privateKey` (string): Wallet private key
- `network` (string, optional): Network identifier
- **Returns:** Transaction hash, wstETH received
#### `unwrap_wsteth`
Unwrap wstETH to stETH.
- **Parameters:**
- `amount` (string): wstETH amount
- `privateKey` (string): Wallet private key
- `network` (string, optional): Network identifier
- **Returns:** Transaction hash, stETH received
#### `get_lido_stats`
Get Lido staking statistics.
- **Parameters:**
- `network` (string, optional): Network identifier
- **Returns:** Total staked, APR, exchange rate
#### `stake_lp_tokens`
Stake LP tokens in a farm.
- **Parameters:**
- `farmContract` (string): MasterChef contract
- `poolId` (number): Pool ID
- `amount` (string): LP amount
- `privateKey` (string): Wallet private key
- `network` (string, optional): Network identifier
- **Returns:** Stake transaction hash
#### `withdraw_lp_tokens`
Withdraw LP tokens from farm.
- **Parameters:**
- `farmContract` (string): MasterChef contract
- `poolId` (number): Pool ID
- `amount` (string): LP amount
- `privateKey` (string): Wallet private key
- `network` (string, optional): Network identifier
- **Returns:** Withdraw transaction hash
#### `get_farming_position`
Get LP farming position.
- **Parameters:**
- `farmContract` (string): MasterChef contract
- `poolId` (number): Pool ID
- `address` (string): User address
- `network` (string, optional): Network identifier
- **Returns:** Staked amount, pending rewards
#### `get_liquid_staking_info`
Get liquid staking token addresses.
- **Parameters:**
- `network` (string, optional): Network identifier
- **Returns:** stETH, wstETH, rETH addresses
---
### 4.9 Lending Module (10 tools)
#### `get_lending_position`
Get user's lending/borrowing position.
- **Parameters:**
- `protocol` (string): Protocol name (aave, compound)
- `address` (string): User address
- `network` (string, optional): Network identifier
- **Returns:** Supplied, borrowed, health factor
#### `get_lending_rates`
Get supply and borrow rates.
- **Parameters:**
- `protocol` (string): Protocol name
- `asset` (string): Asset address
- `network` (string, optional): Network identifier
- **Returns:** Supply APY, borrow APY, utilization
#### `get_lending_protocols`
List supported lending protocols.
- **Parameters:**
- `network` (string, optional): Network identifier
- **Returns:** Protocol names and addresses
#### `calculate_health_factor`
Calculate health factor after action.
- **Parameters:**
- `protocol` (string): Protocol name
- `address` (string): User address
- `action` (string): supply/borrow/withdraw/repay
- `asset` (string): Asset address
- `amount` (string): Action amount
- `network` (string, optional): Network identifier
- **Returns:** New health factor
#### `get_flash_loan_info`
Get flash loan fees and limits.
- **Parameters:**
- `protocol` (string): Protocol name
- `asset` (string): Asset address
- `network` (string, optional): Network identifier
- **Returns:** Fee percentage, max available
#### `get_liquidatable_positions`
Find liquidatable positions.
- **Parameters:**
- `protocol` (string): Protocol name
- `network` (string, optional): Network identifier
- **Returns:** Positions with health factor < 1
#### `supply_to_lending`
Supply assets to earn interest.
- **Parameters:**
- `protocol` (string): Protocol name
- `asset` (string): Asset address
- `amount` (string): Amount to supply
- `privateKey` (string): Wallet private key
- `network` (string, optional): Network identifier
- **Returns:** Supply transaction hash
#### `borrow_from_lending`
Borrow assets.
- **Parameters:**
- `protocol` (string): Protocol name
- `asset` (string): Asset address
- `amount` (string): Amount to borrow
- `privateKey` (string): Wallet private key
- `network` (string, optional): Network identifier
- **Returns:** Borrow transaction hash
#### `repay_to_lending`
Repay borrowed assets.
- **Parameters:**
- `protocol` (string): Protocol name
- `asset` (string): Asset address
- `amount` (string): Amount to repay
- `privateKey` (string): Wallet private key
- `network` (string, optional): Network identifier
- **Returns:** Repay transaction hash
#### `withdraw_from_lending`
Withdraw supplied assets.
- **Parameters:**
- `protocol` (string): Protocol name
- `asset` (string): Asset address
- `amount` (string): Amount to withdraw
- `privateKey` (string): Wallet private key
- `network` (string, optional): Network identifier
- **Returns:** Withdraw transaction hash
---
### 4.10 Bridge Module (6 tools)
#### `get_bridge_quote`
Get quote for cross-chain transfer.
- **Parameters:**
- `fromChain` (string): Source chain
- `toChain` (string): Destination chain
- `token` (string): Token address
- `amount` (string): Amount to bridge
- **Returns:** Fees, estimated time, routes
#### `execute_bridge`
Execute cross-chain bridge.
- **Parameters:**
- `fromChain` (string): Source chain
- `toChain` (string): Destination chain
- `token` (string): Token address
- `amount` (string): Amount to bridge
- `privateKey` (string): Wallet private key
- **Returns:** Transaction hash, bridge ID
#### `get_bridge_status`
Track bridge transaction status.
- **Parameters:**
- `bridgeId` (string): Bridge transaction ID
- `protocol` (string): Bridge protocol
- **Returns:** Status, confirmations, ETA
#### `get_supported_bridges`
List supported bridge protocols.
- **Parameters:**
- `fromChain` (string, optional): Source chain
- `toChain` (string, optional): Destination chain
- **Returns:** Bridge protocols and supported routes
#### `estimate_bridge_time`
Estimate bridge transfer time.
- **Parameters:**
- `fromChain` (string): Source chain
- `toChain` (string): Destination chain
- `protocol` (string): Bridge protocol
- **Returns:** Estimated time in minutes
#### `get_bridge_fees`
Get detailed bridge fee breakdown.
- **Parameters:**
- `fromChain` (string): Source chain
- `toChain` (string): Destination chain
- `token` (string): Token address
- `amount` (string): Amount
- `protocol` (string): Bridge protocol
- **Returns:** Gas fees, protocol fees, total
---
### 4.11 NFT Module (12 tools)
#### `get_nft_info`
Get detailed NFT information.
- **Parameters:**
- `contractAddress` (string): NFT contract
- `tokenId` (string): Token ID
- `network` (string, optional): Network identifier
- **Returns:** Metadata, owner, attributes
#### `get_erc1155_token_metadata`
Get ERC1155 token metadata.
- **Parameters:**
- `contractAddress` (string): Contract address
- `tokenId` (string): Token ID
- `network` (string, optional): Network identifier
- **Returns:** URI, metadata
#### `transfer_nft`
Transfer ERC721 NFT.
- **Parameters:**
- `contractAddress` (string): NFT contract
- `tokenId` (string): Token ID
- `to` (string): Recipient address
- `privateKey` (string): Wallet private key
- `network` (string, optional): Network identifier
- **Returns:** Transfer transaction hash
#### `transfer_erc1155`
Transfer ERC1155 tokens.
- **Parameters:**
- `contractAddress` (string): Contract address
- `tokenId` (string): Token ID
- `to` (string): Recipient address
- `amount` (string): Amount to transfer
- `privateKey` (string): Wallet private key
- `network` (string, optional): Network identifier
- **Returns:** Transfer transaction hash
#### `get_nft_collection_info`
Get NFT collection information.
- **Parameters:**
- `contractAddress` (string): Collection contract
- `network` (string, optional): Network identifier
- **Returns:** Name, symbol, total supply
#### `get_nfts_by_owner`
Get NFT count by owner.
- **Parameters:**
- `contractAddress` (string): NFT contract
- `ownerAddress` (string): Owner address
- `network` (string, optional): Network identifier
- **Returns:** NFT count owned
#### `check_nft_ownership`
Check specific NFT ownership.
- **Parameters:**
- `contractAddress` (string): NFT contract
- `tokenId` (string): Token ID
- `address` (string): Address to check
- `network` (string, optional): Network identifier
- **Returns:** Boolean ownership status
#### `approve_nft_for_marketplace`
Approve NFT for marketplace sale.
- **Parameters:**
- `contractAddress` (string): NFT contract
- `operator` (string): Marketplace address
- `approved` (boolean): Approval status
- `privateKey` (string): Wallet private key
- `network` (string, optional): Network identifier
- **Returns:** Approval transaction hash
#### `revoke_nft_approval`
Revoke NFT operator approval.
- **Parameters:**
- `contractAddress` (string): NFT contract
- `operator` (string): Operator address
- `privateKey` (string): Wallet private key
- `network` (string, optional): Network identifier
- **Returns:** Revocation transaction hash
#### `check_nft_approval`
Check operator approval status.
- **Parameters:**
- `contractAddress` (string): NFT contract
- `owner` (string): Owner address
- `operator` (string): Operator address
- `network` (string, optional): Network identifier
- **Returns:** Approval status
#### `batch_transfer_nfts`
Transfer multiple NFTs.
- **Parameters:**
- `contractAddress` (string): NFT contract
- `transfers` (array): [{tokenId, to}] pairs
- `privateKey` (string): Wallet private key
- `network` (string, optional): Network identifier
- **Returns:** Array of transaction results
#### `fetch_nft_metadata`
Fetch and parse NFT metadata from URI.
- **Parameters:**
- `tokenUri` (string): Metadata URI
- **Returns:** Parsed metadata object
---
### 4.12 Governance Module (6 tools)
#### `get_proposal_details`
Get governance proposal details.
- **Parameters:**
- `governorAddress` (string): Governor contract
- `proposalId` (string): Proposal ID
- `network` (string, optional): Network identifier
- **Returns:** Proposal state, votes, description
#### `cast_vote`
Cast vote on proposal.
- **Parameters:**
- `governorAddress` (string): Governor contract
- `proposalId` (string): Proposal ID
- `support` (number): 0=against, 1=for, 2=abstain
- `privateKey` (string): Wallet private key
- `network` (string, optional): Network identifier
- **Returns:** Vote transaction hash
#### `get_voting_power`
Get voting power at block.
- **Parameters:**
- `governorAddress` (string): Governor contract
- `address` (string): Voter address
- `blockNumber` (number, optional): Block number
- `network` (string, optional): Network identifier
- **Returns:** Voting power amount
#### `get_governance_params`
Get governance parameters.
- **Parameters:**
- `governorAddress` (string): Governor contract
- `network` (string, optional): Network identifier
- **Returns:** Voting delay, period, quorum
#### `check_vote_eligibility`
Check if address can vote.
- **Parameters:**
- `governorAddress` (string): Governor contract
- `proposalId` (string): Proposal ID
- `address` (string): Voter address
- `network` (string, optional): Network identifier
- **Returns:** Eligibility status, voting power
#### `calculate_proposal_id`
Calculate proposal ID from parameters.
- **Parameters:**
- `targets` (array): Target addresses
- `values` (array): ETH values
- `calldatas` (array): Call data
- `descriptionHash` (string): Description hash
- `network` (string, optional): Network identifier
- **Returns:** Calculated proposal ID
---
### 4.13 Price Feeds Module (6 tools)
#### `get_chainlink_price`
Get Chainlink oracle price.
- **Parameters:**
- `pair` (string): Price pair (e.g., "ETH/USD")
- `network` (string, optional): Network identifier
- **Returns:** Price, decimals, timestamp
#### `get_available_price_feeds`
List available Chainlink feeds.
- **Parameters:**
- `network` (string, optional): Network identifier
- **Returns:** Array of available pairs
#### `get_custom_price_feed`
Get price from custom feed address.
- **Parameters:**
- `feedAddress` (string): Chainlink feed address
- `network` (string, optional): Network identifier
- **Returns:** Price, round ID, timestamp
#### `get_multiple_prices`
Get multiple prices in one call.
- **Parameters:**
- `pairs` (array): Array of price pairs
- `network` (string, optional): Network identifier
- **Returns:** Array of prices
#### `get_uniswap_pool_price`
Get Uniswap V3 pool price.
- **Parameters:**
- `poolAddress` (string): Pool address
- `network` (string, optional): Network identifier
- **Returns:** Current price, tick, liquidity
#### `check_price_feed_health`
Check if price feed is stale.
- **Parameters:**
- `feedAddress` (string): Feed address
- `maxAge` (number, optional): Max age in seconds
- `network` (string, optional): Network identifier
- **Returns:** Health status, staleness
---
### 4.14 Events Module (7 tools)
#### `get_contract_logs`
Get event logs from contract.
- **Parameters:**
- `contractAddress` (string): Contract address
- `fromBlock` (number, optional): Start block
- `toBlock` (number, optional): End block
- `network` (string, optional): Network identifier
- **Returns:** Array of event logs
#### `get_erc20_transfers`
Get ERC20 transfer events.
- **Parameters:**
- `tokenAddress` (string): Token address
- `fromBlock` (number, optional): Start block
- `toBlock` (number, optional): End block
- `network` (string, optional): Network identifier
- **Returns:** Array of transfer events
#### `get_approval_events`
Get ERC20 approval events.
- **Parameters:**
- `tokenAddress` (string): Token address
- `fromBlock` (number, optional): Start block
- `toBlock` (number, optional): End block
- `network` (string, optional): Network identifier
- **Returns:** Array of approval events
#### `get_logs_by_topic`
Get logs filtered by topic.
- **Parameters:**
- `topic0` (string): Event signature hash
- `fromBlock` (number, optional): Start block
- `toBlock` (number, optional): End block
- `network` (string, optional): Network identifier
- **Returns:** Filtered event logs
#### `get_event_topics`
Get common event topic hashes.
- **Parameters:** None
- **Returns:** Map of event names to topic hashes
#### `calculate_event_signature`
Calculate keccak256 topic hash.
- **Parameters:**
- `eventSignature` (string): Event signature string
- **Returns:** Topic hash
#### `get_recent_events`
Get events from recent blocks.
- **Parameters:**
- `contractAddress` (string): Contract address
- `blocks` (number, optional): Number of blocks. Default: 100
- `network` (string, optional): Network identifier
- **Returns:** Recent event logs
---
### 4.15 Multicall Module (6 tools)
#### `execute_multicall`
Execute multiple contract calls.
- **Parameters:**
- `calls` (array): [{target, callData}] array
- `network` (string, optional): Network identifier
- **Returns:** Array of call results
#### `get_multi_token_balances`
Get multiple token balances.
- **Parameters:**
- `address` (string): Wallet address
- `tokenAddresses` (array): Token addresses
- `network` (string, optional): Network identifier
- **Returns:** Array of balances
#### `get_multi_token_info`
Get info for multiple tokens.
- **Parameters:**
- `tokenAddresses` (array): Token addresses
- `network` (string, optional): Network identifier
- **Returns:** Array of token info
#### `get_multi_native_balances`
Get native balances for multiple addresses.
- **Parameters:**
- `addresses` (array): Wallet addresses
- `network` (string, optional): Network identifier
- **Returns:** Array of balances
#### `encode_call_data`
Encode function call data.
- **Parameters:**
- `functionSignature` (string): Function signature
- `args` (array): Function arguments
- **Returns:** Encoded call data
#### `batch_check_allowances`
Check multiple allowances.
- **Parameters:**
- `owner` (string): Token owner
- `checks` (array): [{token, spender}] pairs
- `network` (string, optional): Network identifier
- **Returns:** Array of allowances
---
### 4.16 Signatures Module (7 tools)
#### `sign_message`
Sign message with EIP-191.
- **Parameters:**
- `message` (string): Message to sign
- `privateKey` (string): Wallet private key
- **Returns:** Signature
#### `verify_message_signature`
Verify EIP-191 signature.
- **Parameters:**
- `message` (string): Original message
- `signature` (string): Signature to verify
- `expectedSigner` (string, optional): Expected signer
- **Returns:** Recovered address, validity
#### `sign_typed_data`
Sign EIP-712 typed data.
- **Parameters:**
- `domain` (object): Domain separator
- `types` (object): Type definitions
- `primaryType` (string): Primary type name
- `message` (object): Message to sign
- `privateKey` (string): Wallet private key
- **Returns:** Signature
#### `verify_typed_data_signature`
Verify EIP-712 signature.
- **Parameters:**
- `domain` (object): Domain separator
- `types` (object): Type definitions
- `primaryType` (string): Primary type
- `message` (object): Signed message
- `signature` (string): Signature
- **Returns:** Recovered address, validity
#### `hash_message`
Hash message with EIP-191.
- **Parameters:**
- `message` (string): Message to hash
- **Returns:** Message hash
#### `create_permit_signature`
Create EIP-2612 permit signature.
- **Parameters:**
- `tokenAddress` (string): Token address
- `spender` (string): Spender address
- `value` (string): Approval value
- `deadline` (number): Expiry timestamp
- `privateKey` (string): Wallet private key
- `network` (string, optional): Network identifier
- **Returns:** Permit signature (v, r, s)
#### `recover_signer`
Recover signer from signature.
- **Parameters:**
- `message` (string): Signed message
- `signature` (string): Signature
- **Returns:** Recovered signer address
---
### 4.17 Deployment Module (6 tools)
#### `deploy_contract`
Deploy contract from bytecode.
- **Parameters:**
- `bytecode` (string): Contract bytecode
- `abi` (array): Contract ABI
- `constructorArgs` (array, optional): Constructor arguments
- `privateKey` (string): Deployer private key
- `network` (string, optional): Network identifier
- **Returns:** Deployed address, tx hash
#### `deploy_create2`
Deploy with CREATE2.
- **Parameters:**
- `bytecode` (string): Contract bytecode
- `salt` (string): Salt for address derivation
- `privateKey` (string): Deployer private key
- `network` (string, optional): Network identifier
- **Returns:** Deployed address, tx hash
#### `deploy_proxy`
Deploy proxy contract.
- **Parameters:**
- `implementationAddress` (string): Implementation address
- `proxyType` (string): "uups" or "transparent"
- `initData` (string, optional): Initialization data
- `privateKey` (string): Deployer private key
- `network` (string, optional): Network identifier
- **Returns:** Proxy address, tx hash
#### `upgrade_proxy`
Upgrade proxy implementation.
- **Parameters:**
- `proxyAddress` (string): Proxy address
- `newImplementation` (string): New implementation
- `privateKey` (string): Admin private key
- `network` (string, optional): Network identifier
- **Returns:** Upgrade transaction hash
#### `verify_contract`
Verify contract on explorer.
- **Parameters:**
- `contractAddress` (string): Contract address
- `sourceCode` (string): Source code
- `contractName` (string): Contract name
- `compilerVersion` (string): Compiler version
- `constructorArgs` (string, optional): Encoded args
- `network` (string, optional): Network identifier
- **Returns:** Verification status
#### `predict_create2_address`
Calculate CREATE2 address.
- **Parameters:**
- `deployer` (string): Factory address
- `bytecodeHash` (string): Init code hash
- `salt` (string): Salt value
- **Returns:** Predicted address
---
### 4.18 Domains Module (12 tools)
#### `resolve_ens_name`
Resolve ENS to address.
- **Parameters:**
- `name` (string): ENS name (e.g., "vitalik.eth")
- **Returns:** Resolved address
#### `reverse_resolve_address`
Get ENS name for address.
- **Parameters:**
- `address` (string): Ethereum address
- **Returns:** Primary ENS name
#### `get_ens_text_records`
Get ENS text records.
- **Parameters:**
- `name` (string): ENS name
- `keys` (array, optional): Record keys to fetch
- **Returns:** Text record values
#### `get_ens_avatar`
Get ENS avatar URL.
- **Parameters:**
- `name` (string): ENS name
- **Returns:** Avatar URL
#### `check_ens_availability`
Check ENS availability.
- **Parameters:**
- `name` (string): Name to check (without .eth)
- **Returns:** Availability status, price
#### `get_ens_name_details`
Get comprehensive ENS details.
- **Parameters:**
- `name` (string): ENS name
- **Returns:** Owner, resolver, expiry, records
#### `batch_resolve_addresses`
Reverse resolve multiple addresses.
- **Parameters:**
- `addresses` (array): Addresses to resolve
- **Returns:** Array of ENS names
#### `register_ens_name`
Register new ENS name.
- **Parameters:**
- `name` (string): Name to register
- `duration` (number): Registration years
- `privateKey` (string): Wallet private key
- **Returns:** Registration transaction hash
#### `set_ens_records`
Set ENS records.
- **Parameters:**
- `name` (string): ENS name
- `records` (object): {address, text, contenthash}
- `privateKey` (string): Owner private key
- **Returns:** Transaction hash
#### `transfer_ens`
Transfer ENS ownership.
- **Parameters:**
- `name` (string): ENS name
- `newOwner` (string): New owner address
- `privateKey` (string): Current owner key
- **Returns:** Transfer transaction hash
#### `renew_ens`
Extend ENS registration.
- **Parameters:**
- `name` (string): ENS name
- `duration` (number): Additional years
- `privateKey` (string): Wallet private key
- **Returns:** Renewal transaction hash
#### `create_subdomain`
Create ENS subdomain.
- **Parameters:**
- `parentName` (string): Parent ENS name
- `label` (string): Subdomain label
- `owner` (string): Subdomain owner
- `privateKey` (string): Parent owner key
- **Returns:** Transaction hash
---
### 4.19 MEV Module (4 tools)
#### `send_private_transaction`
Send via Flashbots Protect.
- **Parameters:**
- `to` (string): Target address
- `value` (string, optional): Value in wei
- `data` (string, optional): Call data
- `privateKey` (string): Wallet private key
- `network` (string, optional): Network (ethereum)
- **Returns:** Transaction hash
#### `simulate_bundle`
Simulate transaction bundle.
- **Parameters:**
- `transactions` (array): Signed transactions
- `blockNumber` (number, optional): Target block
- `network` (string, optional): Network identifier
- **Returns:** Simulation results
#### `check_mev_exposure`
Analyze MEV exposure.
- **Parameters:**
- `txHash` (string): Transaction hash
- `network` (string, optional): Network identifier
- **Returns:** MEV risk assessment
#### `get_mev_protection_info`
Get MEV protection options.
- **Parameters:**
- `network` (string, optional): Network identifier
- **Returns:** Available protection methods
---
### 4.20 Portfolio Module (5 tools)
#### `get_portfolio_overview`
Get comprehensive portfolio.
- **Parameters:**
- `address` (string): Wallet address
- `network` (string, optional): Network identifier
- **Returns:** Balances, total value, allocations
#### `get_token_balance`
Get specific token balance.
- **Parameters:**
- `address` (string): Wallet address
- `tokenAddress` (string): Token address
- `network` (string, optional): Network identifier
- **Returns:** Balance with USD value
#### `get_multichain_portfolio`
Get portfolio across chains.
- **Parameters:**
- `address` (string): Wallet address
- `networks` (array, optional): Networks to check
- **Returns:** Multi-chain balances
#### `get_wallet_activity`
Get recent wallet activity.
- **Parameters:**
- `address` (string): Wallet address
- `network` (string, optional): Network identifier
- **Returns:** Transaction count, activity level
#### `calculate_portfolio_allocation`
Calculate allocation percentages.
- **Parameters:**
- `address` (string): Wallet address
- `network` (string, optional): Network identifier
- **Returns:** Allocation by token/category
---
### 4.21 Market Data Module (25+ tools)
#### CoinStats Tools
##### `market_get_coins`
Get cryptocurrency data with filtering.
- **Parameters:**
- `name` (string, optional): Search by name
- `page` (number, optional): Page number
- `limit` (number, optional): Results per page
- `currency` (string, optional): Price currency
- `symbol` (string, optional): Filter by symbol
- `blockchains` (string, optional): Chain filter
- `categories` (string, optional): Category filter
- `sortBy` (string, optional): Sort field
- `sortDir` (string, optional): asc/desc
- `marketCapGreaterThan` (number, optional): Min market cap
- `volumeGreaterThan` (number, optional): Min volume
- **Returns:** Coin list with prices and metrics
##### `market_get_coin_by_id`
Get specific coin details.
- **Parameters:**
- `coinId` (string): Coin identifier
- `currency` (string, optional): Price currency
- **Returns:** Detailed coin information
##### `market_get_coin_chart`
Get historical chart data.
- **Parameters:**
- `coinId` (string): Coin identifier
- `period` (string): 24h/1w/1m/3m/6m/1y/all
- **Returns:** OHLCV chart data
##### `market_get_trending`
Get trending cryptocurrencies.
- **Parameters:**
- `limit` (number, optional): Number of results
- **Returns:** Trending coins list
##### `market_get_exchanges`
Get exchange information.
- **Parameters:**
- `limit` (number, optional): Number of results
- **Returns:** Exchange list with volume
##### `market_get_fear_greed_index`
Get Fear & Greed Index.
- **Parameters:**
- `limit` (number, optional): Historical data points
- **Returns:** Index value and classification
#### CoinGecko Tools
##### `coingecko_get_coin`
Get CoinGecko coin data.
- **Parameters:**
- `id` (string): CoinGecko coin ID
- **Returns:** Comprehensive coin data
##### `coingecko_get_markets`
Get market data for coins.
- **Parameters:**
- `vs_currency` (string, optional): Quote currency
- `order` (string, optional): Sort order
- `per_page` (number, optional): Results per page
- `page` (number, optional): Page number
- **Returns:** Market data array
##### `coingecko_get_price`
Get simple price.
- **Parameters:**
- `ids` (string): Coin IDs (comma-separated)
- `vs_currencies` (string): Quote currencies
- **Returns:** Price map
##### `coingecko_get_ohlc`
Get OHLC data.
- **Parameters:**
- `id` (string): Coin ID
- `vs_currency` (string): Quote currency
- `days` (number): Data days (1/7/14/30/90/180/365)
- **Returns:** OHLC array
##### `coingecko_get_categories`
Get coin categories.
- **Parameters:** None
- **Returns:** Category list with market cap
##### `coingecko_get_exchanges`
Get exchange data.
- **Parameters:**
- `per_page` (number, optional): Results per page
- **Returns:** Exchange list
##### `coingecko_get_derivatives`
Get derivatives data.
- **Parameters:** None
- **Returns:** Derivatives market data
##### `coingecko_get_company_holdings`
Get company BTC/ETH holdings.
- **Parameters:**
- `coin` (string): "bitcoin" or "ethereum"
- **Returns:** Company holdings list
---
### 4.22 DeFi Analytics Module (DefiLlama)
#### `defi_get_protocols`
Get all DeFi protocols.
- **Parameters:** None
- **Returns:** Protocol list with TVL
#### `defi_get_protocol`
Get specific protocol data.
- **Parameters:**
- `protocol` (string): Protocol slug
- **Returns:** Detailed protocol info
#### `defi_get_protocol_tvl`
Get protocol TVL history.
- **Parameters:**
- `protocol` (string): Protocol slug
- **Returns:** Historical TVL data
#### `defi_get_chains`
Get chain TVL data.
- **Parameters:** None
- **Returns:** All chains with TVL
#### `defi_get_chain_tvl`
Get chain TVL history.
- **Parameters:**
- `chain` (string): Chain name
- **Returns:** Historical chain TVL
#### `defi_get_chain_protocols`
Get protocols on a chain.
- **Parameters:**
- `chain` (string): Chain name
- **Returns:** Chain protocols sorted by TVL
#### `defi_get_yields`
Get yield farming data.
- **Parameters:**
- `chain` (string, optional): Filter by chain
- `project` (string, optional): Filter by project
- `minTvl` (number, optional): Min TVL filter
- `minApy` (number, optional): Min APY filter
- **Returns:** Yield pools sorted by APY
#### `defi_get_yield_pool`
Get specific yield pool.
- **Parameters:**
- `poolId` (string): Pool identifier
- **Returns:** Pool details with APY history
#### `defi_get_fees`
Get protocol fees/revenue.
- **Parameters:**
- `protocol` (string, optional): Protocol slug
- **Returns:** Fees and revenue data
#### `defi_get_stablecoins`
Get stablecoin data.
- **Parameters:** None
- **Returns:** Stablecoin market caps and pegs
#### `defi_get_bridges`
Get bridge volume data.
- **Parameters:** None
- **Returns:** Bridge volumes and flows
#### `defi_get_hacks`
Get DeFi hacks history.
- **Parameters:** None
- **Returns:** Historical hack data
#### `defi_get_liquidations`
Get liquidation data.
- **Parameters:**
- `protocol` (string, optional): Protocol filter
- **Returns:** Liquidation amounts
---
### 4.23 DEX Analytics Module
#### DexPaprika Tools
##### `dex_get_networks`
Get supported networks.
- **Parameters:** None
- **Returns:** Network list with IDs
##### `dex_get_network_dexes`
Get DEXes on network.
- **Parameters:**
- `networkId` (string): Network identifier
- **Returns:** DEX list
##### `dex_get_network_pools`
Get top pools on network.
- **Parameters:**
- `networkId` (string): Network identifier
- `page` (number, optional): Page number
- `limit` (number, optional): Results per page
- **Returns:** Pool list with liquidity
##### `dex_get_dex_pools`
Get pools from specific DEX.
- **Parameters:**
- `networkId` (string): Network identifier
- `dexId` (string): DEX identifier
- **Returns:** DEX pools
##### `dex_get_pool_details`
Get pool details.
- **Parameters:**
- `networkId` (string): Network identifier
- `poolAddress` (string): Pool address
- **Returns:** Pool info with reserves
##### `dex_get_token_details`
Get token details.
- **Parameters:**
- `networkId` (string): Network identifier
- `tokenAddress` (string): Token address
- **Returns:** Token info with price
##### `dex_get_token_pools`
Get pools for token.
- **Parameters:**
- `networkId` (string): Network identifier
- `tokenAddress` (string): Token address
- **Returns:** Token's liquidity pools
##### `dex_get_pool_ohlcv`
Get pool OHLCV data.
- **Parameters:**
- `networkId` (string): Network identifier
- `poolAddress` (string): Pool address
- `interval` (string, optional): Candle interval
- **Returns:** OHLCV candles
##### `dex_get_pool_transactions`
Get pool transactions.
- **Parameters:**
- `networkId` (string): Network identifier
- `poolAddress` (string): Pool address
- `limit` (number, optional): Transaction limit
- **Returns:** Recent swaps
##### `dex_search`
Search across networks.
- **Parameters:**
- `query` (string): Search query
- **Returns:** Matching tokens, pools, DEXes
##### `dex_get_stats`
Get ecosystem statistics.
- **Parameters:** None
- **Returns:** High-level metrics
##### `dex_get_multi_prices`
Get batched token prices.
- **Parameters:**
- `networkId` (string): Network identifier
- `tokenAddresses` (array): Token addresses
- **Returns:** Price map
#### GeckoTerminal Tools
##### `geckoterminal_get_networks`
Get GeckoTerminal networks.
- **Parameters:** None
- **Returns:** Supported networks
##### `geckoterminal_get_dexes`
Get network DEXes.
- **Parameters:**
- `network` (string): Network identifier
- **Returns:** DEX list
##### `geckoterminal_trending_pools`
Get trending pools.
- **Parameters:**
- `network` (string, optional): Filter by network
- **Returns:** Trending pools
##### `geckoterminal_new_pools`
Get newly created pools.
- **Parameters:**
- `network` (string, optional): Filter by network
- **Returns:** New pool launches
##### `geckoterminal_top_pools`
Get top pools by metrics.
- **Parameters:**
- `network` (string): Network identifier
- `sort` (string, optional): Sort metric
- **Returns:** Top pools
##### `geckoterminal_get_pool`
Get pool by address.
- **Parameters:**
- `network` (string): Network identifier
- `poolAddress` (string): Pool address
- **Returns:** Pool details
##### `geckoterminal_get_multi_pools`
Get multiple pools.
- **Parameters:**
- `network` (string): Network identifier
- `poolAddresses` (array): Pool addresses
- **Returns:** Pool details array
##### `geckoterminal_pool_ohlcv`
Get pool candlestick data.
- **Parameters:**
- `network` (string): Network identifier
- `poolAddress` (string): Pool address
- `timeframe` (string, optional): Candle timeframe
- **Returns:** OHLCV data
##### `geckoterminal_pool_trades`
Get pool trades.
- **Parameters:**
- `network` (string): Network identifier
- `poolAddress` (string): Pool address
- **Returns:** Recent trades
##### `geckoterminal_get_token`
Get token info.
- **Parameters:**
- `network` (string): Network identifier
- `tokenAddress` (string): Token address
- **Returns:** Token details with price
---
### 4.24 Social Module (LunarCrush)
#### `social_get_coin_metrics`
Get coin social metrics.
- **Parameters:**
- `symbol` (string): Coin symbol (BTC, ETH)
- **Returns:** Galaxy Score, AltRank, sentiment
#### `social_get_coins_list`
Get social metrics for multiple coins.
- **Parameters:**
- `sort` (string, optional): Sort metric
- `limit` (number, optional): Result count
- `desc` (boolean, optional): Sort descending
- **Returns:** Coins with social metrics
#### `social_get_coin_time_series`
Get historical social metrics.
- **Parameters:**
- `symbol` (string): Coin symbol
- `interval` (string, optional): hour/day/week
- `start` (number, optional): Start timestamp
- `end` (number, optional): End timestamp
- **Returns:** Time series data
#### `social_get_feed`
Get social posts.
- **Parameters:**
- `symbol` (string, optional): Filter by coin
- `source` (string, optional): twitter/reddit/news
- `limit` (number, optional): Post count
- **Returns:** Social posts
#### `social_get_trending_posts`
Get trending posts.
- **Parameters:**
- `type` (string, optional): rising/hot/top
- `limit` (number, optional): Post count
- **Returns:** Trending posts
#### `social_get_influencers`
Get crypto influencers.
- **Parameters:**
- `symbol` (string, optional): Filter by coin
- `sort` (string, optional): Sort metric
- `limit` (number, optional): Result count
- **Returns:** Influencer rankings
#### `social_get_trending_topics`
Get trending topics.
- **Parameters:**
- `limit` (number, optional): Topic count
- **Returns:** Trending topics
#### `social_get_market_sentiment`
Get overall market sentiment.
- **Parameters:** None
- **Returns:** Bullish/bearish sentiment index
#### `social_get_galaxy_score`
Get Galaxy Score for coin.
- **Parameters:**
- `symbol` (string): Coin symbol
- **Returns:** Galaxy Score components
#### `social_get_alt_rank`
Get AltRank for coin.
- **Parameters:**
- `symbol` (string): Coin symbol
- **Returns:** AltRank position
---
### 4.25 News Module (7 tools)
#### `get_crypto_news`
Get latest crypto news.
- **Parameters:**
- `limit` (number, optional): Article count (1-50)
- `source` (string, optional): Filter by source
- **Returns:** News articles
**Sources:** CoinDesk, The Block, Decrypt, CoinTelegraph, Bitcoin Magazine, Blockworks, The Defiant
#### `search_crypto_news`
Search news by keywords.
- **Parameters:**
- `keywords` (string): Comma-separated keywords
- `limit` (number, optional): Result count
- **Returns:** Matching articles
#### `get_defi_news`
Get DeFi-specific news.
- **Parameters:**
- `limit` (number, optional): Article count
- **Returns:** DeFi news articles
#### `get_bitcoin_news`
Get Bitcoin-specific news.
- **Parameters:**
- `limit` (number, optional): Article count
- **Returns:** Bitcoin news articles
#### `get_breaking_crypto_news`
Get breaking news (last 2 hours).
- **Parameters:**
- `limit` (number, optional): Article count
- **Returns:** Breaking news
#### `get_news_sources`
Get available news sources.
- **Parameters:** None
- **Returns:** Source list with status
#### `get_news_by_category`
Get news by category.
- **Parameters:**
- `category` (string): News category
- `limit` (number, optional): Article count
- **Returns:** Categorized news
---
## 5. Data Provider Integrations
| Provider | Data Type | API Key | Rate Limits |
|----------|-----------|---------|-------------|
| **CoinGecko** | Market data, prices, OHLCV | Optional | Free: 10-30 req/min |
| **CoinStats** | Portfolio, prices, wallets | Required | Varies by plan |
| **DefiLlama** | TVL, yields, fees, protocols | Not required | Generous |
| **LunarCrush** | Social sentiment, influencers | Required | Varies |
| **GoPlus** | Security analysis, honeypots | Not required | Generous |
| **GeckoTerminal** | DEX pools, trades, OHLCV | Not required | 30 req/min |
| **DexPaprika** | DEX analytics, pools | Not required | Generous |
| **CryptoPanic** | News aggregation | Required | Varies |
| **Alternative.me** | Fear & Greed Index | Not required | Generous |
---
## 6. Environment Variables
### Required for Write Operations
```bash
PRIVATE_KEY=0x... # Wallet private key
```
### Optional API Keys
```bash
# Market Data
COINGECKO_API_KEY=CG-xxx # Higher rate limits
COINSTATS_API_KEY=xxx # CoinStats access
# Social Data
LUNARCRUSH_API_KEY=xxx # Social metrics
CRYPTOCOMPARE_API_KEY=xxx # Fallback social data
# News
CRYPTOPANIC_API_KEY=xxx # News feeds
# Custom RPC
RPC_URL=https://... # Custom RPC endpoint
# Server Configuration
PORT=3001 # HTTP/SSE server port
LOG_LEVEL=INFO # DEBUG, INFO, WARN, ERROR
```
---
## 7. Server Modes
### stdio Mode (Default)
For Claude Desktop and Cursor:
```bash
npx @nirholas/bnb-chain-mcp@latest
```
### HTTP Mode
For ChatGPT Developer Mode:
```bash
npx @nirholas/bnb-chain-mcp@latest --http
# Server runs on http://localhost:3001/mcp
```
### SSE Mode
For legacy HTTP clients:
```bash
npx @nirholas/bnb-chain-mcp@latest --sse
# Server runs on http://localhost:3001/sse
```
---
## 8. Error Handling
### Common Error Responses
```json
{
"content": [{
"type": "text",
"text": "Error: [error message]"
}],
"isError": true
}
```
### Error Categories
| Error Type | Description | Resolution |
|------------|-------------|------------|
| `INSUFFICIENT_FUNDS` | Not enough balance | Check wallet balance |
| `INVALID_ADDRESS` | Malformed address | Verify address format |
| `NETWORK_ERROR` | RPC connection failed | Check network/RPC |
| `RATE_LIMITED` | API rate limit hit | Wait or use API key |
| `UNAUTHORIZED` | Missing API key | Set required env var |
| `SIMULATION_FAILED` | Transaction would fail | Check parameters |
| `GAS_ESTIMATION_FAILED` | Cannot estimate gas | Verify contract state |
---
## 9. Examples & Use Cases
### Example 1: Check Token Security
```
User: Check if token 0x... is safe on BSC
AI uses: goplus_token_security
- Checks honeypot status
- Analyzes holder distribution
- Detects malicious code patterns
- Returns risk assessment
```
### Example 2: Execute Token Swap
```
User: Swap 1 ETH for USDC on Arbitrum
AI uses:
1. get_swap_quote - Get expected output
2. execute_swap - Execute the swap with slippage protection
```
### Example 3: Portfolio Analysis
```
User: Show my portfolio on Ethereum
AI uses:
1. get_wallet_portfolio - Native + token balances
2. market_get_coins - Current prices
3. calculate_portfolio_allocation - Allocation breakdown
```
### Example 4: DeFi Yield Farming
```
User: Find best yields on Arbitrum with >$1M TVL
AI uses:
1. defi_get_yields with chain and TVL filters
2. Returns sorted pools with APY breakdown
```
### Example 5: Cross-Chain Bridge
```
User: Bridge 100 USDC from Ethereum to Arbitrum
AI uses:
1. get_bridge_quote - Compare bridge options
2. execute_bridge - Execute transfer
3. get_bridge_status - Track completion
```
---
## Links & Resources
- **Documentation**: https://bnb-chain-mcp.vercel.app
- **GitHub**: https://github.com/nirholas/bnb-chain-mcp
- **npm Package**: @nirholas/bnb-chain-mcp
- **Author**: [nich](https://x.com/nichxbt)
---
*Last updated: January 2026*
*Version: 0.1.0*
