sperax-crypto-mcp / BNB-Chain-MCP

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