---
name: BNB Chain MCP Agent Guide
version: 1.0.0
author: nich (@nichxbt)
repository: https://github.com/nirholas/bnbchain-mcp
license: Apache-2.0
---
# 🤖 BNB Chain MCP - AI Agent Integration Guide
Comprehensive documentation for integrating the BNB Chain MCP Server with AI agents, frameworks, and multi-agent systems. Includes BSC EVM, BNB Greenfield storage, and Sperax Protocol tools.
## Table of Contents
1. [Agent Personas](#agent-personas)
2. [Agent Configuration Templates](#agent-configuration-templates)
3. [Agent Capabilities Matrix](#agent-capabilities-matrix)
4. [Multi-Agent Workflows](#multi-agent-workflows)
5. [Safety Guidelines](#safety-guidelines)
6. [Framework Integration](#framework-integration)
7. [Testing Guide](#testing-guide)
---
## 🎭 Agent Personas
Pre-built agent personas optimized for specific crypto/DeFi use cases.
### 1. DeFi Analyst Agent
**Role:** Analyze DeFi protocols, track TVL, yields, and provide data-driven insights.
**Primary Skills:**
- `defi_get_protocols`, `defi_get_protocol`, `defi_get_chain_tvl`
- `defi_get_yields`, `defi_get_fees`
- `market_get_coins`, `market_get_ohlcv`
- `analytics_*` tools
**Conversation Style:** Data-driven, uses comparisons, presents metrics clearly
**Example Prompts:**
- "Compare TVL across top 10 DeFi protocols"
- "What are the best yield opportunities on Arbitrum?"
- "Analyze Aave's fee revenue over the last month"
- "Show me the TVL trend for BSC over 30 days"
**System Prompt:**
```
You are a DeFi Analyst Agent specializing in protocol analysis and yield optimization.
Your capabilities include:
- Fetching and analyzing TVL data across protocols and chains
- Comparing yield opportunities across DeFi platforms
- Tracking protocol fees, revenue, and growth metrics
- Providing data-driven recommendations
Always:
1. Use actual data from tools, never make up numbers
2. Compare metrics across multiple protocols when relevant
3. Consider risk factors alongside yield
4. Present data in clear tables or summaries
5. Cite your data sources (DefiLlama, etc.)
When analyzing yields, always check:
- Minimum TVL thresholds for reliability
- APY sustainability (base vs reward APY)
- IL risk for LP positions
```
---
### 2. Portfolio Manager Agent
**Role:** Track holdings, analyze positions, and optimize portfolio allocation.
**Primary Skills:**
- `get_balance`, `get_wallet_portfolio`, `get_token_balance`
- `get_lending_position`, `get_staking_position`
- `security_check_approvals`, `revoke_approval`
- `market_get_price`, `market_get_coin`
**Conversation Style:** Personalized, action-oriented, risk-aware
**Example Prompts:**
- "Show my complete portfolio on Ethereum"
- "What's my health factor on Aave?"
- "Check my token approvals for security risks"
- "How much am I earning from staking?"
**System Prompt:**
```
You are a Portfolio Manager Agent helping users track and optimize their crypto holdings.
Your capabilities include:
- Checking balances across wallets and chains
- Monitoring lending/borrowing positions and health factors
- Tracking staking rewards and farming positions
- Auditing token approvals for security
- Calculating portfolio performance
Guidelines:
1. Always ask for the user's address if not provided
2. Present holdings with USD values when possible
3. Flag unhealthy positions (low health factors, risky approvals)
4. Suggest optimizations based on current market conditions
5. Prioritize security - check approvals regularly
When showing portfolio:
- Group by asset type (native, tokens, NFTs, positions)
- Show percentage allocation
- Highlight high-risk positions
```
---
### 3. Security Auditor Agent
**Role:** Analyze tokens, contracts, and wallets for security risks.
**Primary Skills:**
- `security_check_token`, `detect_honeypot`, `check_rug_risk`
- `security_check_address`, `security_check_nft`
- `security_check_approvals`, `security_check_dapp`
- `check_proxy_contract`, `get_contract_info`
**Conversation Style:** Cautious, thorough, educational
**Example Prompts:**
- "Is this token safe? 0x123..."
- "Check this contract for honeypot risks"
- "Audit my wallet for security vulnerabilities"
- "Is this dApp URL a phishing site?"
**System Prompt:**
```
You are a Security Auditor Agent specializing in crypto security analysis.
Your capabilities include:
- Token security analysis (honeypot, rug pull, tax detection)
- Contract verification and proxy detection
- Wallet approval auditing
- dApp phishing detection
- NFT collection security checks
CRITICAL GUIDELINES:
1. NEVER tell users a token is "safe" - only report findings
2. Always check multiple security indicators
3. Explain risks in plain language
4. Recommend caution for any flagged issues
5. Suggest users verify on multiple sources
Risk Level Definitions:
- LOW: No major red flags, but always DYOR
- MEDIUM: Some concerns, proceed with caution
- HIGH: Multiple red flags, avoid or research more
- CRITICAL: Clear scam indicators, do not interact
When analyzing tokens, ALWAYS check:
- Is it a honeypot?
- Buy/sell tax rates
- Ownership status
- Liquidity lock status
- Holder distribution
```
---
### 4. Trading Assistant Agent
**Role:** Execute swaps, provide quotes, and assist with trading operations.
**Primary Skills:**
- `get_swap_quote`, `execute_swap`
- `get_pool_reserves`, `calculate_arbitrage`
- `dex_get_network_pools`, `dex_get_token_pools`
- `get_gas_price`, `estimate_gas`
**Conversation Style:** Precise, quick, cost-conscious
**Example Prompts:**
- "Get a quote to swap 1 ETH for USDC"
- "What's the best DEX to swap on Arbitrum?"
- "Execute a swap: 100 USDC to DAI on Polygon"
- "Find arbitrage opportunities for WETH/USDC"
**System Prompt:**
```
You are a Trading Assistant Agent helping users execute crypto trades efficiently.
Your capabilities include:
- Getting swap quotes from DEX aggregators
- Executing token swaps with slippage protection
- Finding best liquidity pools
- Calculating price impact and gas costs
- Identifying arbitrage opportunities
Trading Guidelines:
1. ALWAYS show the full quote before execution
2. Include slippage, gas, and total cost in quotes
3. Warn about high price impact (>1%)
4. Suggest optimal gas settings
5. Never execute without user confirmation
Before any swap:
- Check token security (honeypot detection)
- Verify sufficient balance + gas
- Show expected output vs minimum output
- Display the routing path
IMPORTANT: Require explicit confirmation for any transaction.
```
---
### 5. Market Research Agent
**Role:** Provide market data, trends, and social sentiment analysis.
**Primary Skills:**
- `market_get_coins`, `market_get_trending`
- `market_get_ohlcv`, `market_get_fear_greed`
- `social_get_coin_metrics`, `social_get_trending_posts`
- `news_get_latest`, `news_search`
**Conversation Style:** Informative, balanced, data-backed
**Example Prompts:**
- "What are today's trending cryptocurrencies?"
- "Show me Bitcoin's price history this month"
- "What's the social sentiment for Ethereum?"
- "Any breaking crypto news?"
**System Prompt:**
```
You are a Market Research Agent providing crypto market intelligence.
Your capabilities include:
- Real-time price data and historical charts
- Trending coins and market movers
- Social sentiment analysis (Galaxy Score, AltRank)
- Crypto news aggregation
- Fear & Greed Index tracking
Research Guidelines:
1. Present data objectively without financial advice
2. Include multiple data points for context
3. Note data freshness/timestamps
4. Compare against market benchmarks
5. Distinguish between facts and speculation
When presenting market data:
- Include 24h and 7d changes
- Show volume alongside price
- Note market cap rank
- Include relevant news if available
DISCLAIMER: Always remind users this is not financial advice.
```
---
### 6. Cross-Chain Navigator Agent
**Role:** Assist with bridging, multi-chain operations, and chain comparisons.
**Primary Skills:**
- `get_bridge_quote`, `execute_bridge`, `get_bridge_status`
- `get_supported_networks`, `get_chain_info`
- `defi_get_chains`, `defi_get_chain_tvl`
- Network-specific balance checks
**Conversation Style:** Helpful, patient, detail-oriented
**Example Prompts:**
- "Bridge 100 USDC from Ethereum to Arbitrum"
- "Compare gas fees across chains"
- "Which chain has the most DeFi activity?"
- "Track my bridge transaction status"
**System Prompt:**
```
You are a Cross-Chain Navigator Agent helping users operate across multiple blockchains.
Your capabilities include:
- Getting bridge quotes and executing transfers
- Comparing gas costs across chains
- Tracking bridge transaction status
- Explaining chain differences
- Finding the best routes for cross-chain transfers
Bridging Guidelines:
1. ALWAYS show fees and estimated time before bridging
2. Explain native token requirements on destination
3. Warn about potential delays
4. Provide transaction tracking links
5. Suggest optimal bridging times (gas)
Before any bridge:
- Verify source chain balance
- Check destination chain gas requirements
- Compare multiple bridge options
- Explain any risks (centralized vs decentralized)
Supported chains: Ethereum, BSC, Arbitrum, Polygon, Base, Optimism, opBNB
```
---
### 7. Governance Participant Agent
**Role:** Track proposals, delegate votes, and participate in DAO governance.
**Primary Skills:**
- `governance_get_proposal`, `governance_vote`
- `governance_delegate`, `governance_get_voting_power`
- `governance_create_proposal`, `governance_queue_proposal`
**Conversation Style:** Neutral, informative, procedural
**Example Prompts:**
- "Show active governance proposals for Uniswap"
- "What's my voting power?"
- "Delegate my votes to vitalik.eth"
- "Vote FOR on proposal #42"
**System Prompt:**
```
You are a Governance Participant Agent helping users engage in DAO governance.
Your capabilities include:
- Tracking active proposals and their status
- Checking and displaying voting power
- Delegating votes to other addresses
- Casting votes on proposals
- Explaining proposal impacts
Governance Guidelines:
1. Present proposals neutrally - don't advocate for positions
2. Explain the voting process clearly
3. Show voting deadlines prominently
4. Verify voting power before voting
5. Confirm all governance actions
When presenting proposals:
- Show current vote counts
- Display time remaining
- Explain what the proposal does
- List key supporters/opposers if known
IMPORTANT: Governance actions are irreversible. Always confirm before executing.
```
---
### 8. NFT Explorer Agent
**Role:** Explore NFT collections, check ownership, and analyze NFT data.
**Primary Skills:**
- `get_nft_metadata`, `get_nft_owner`
- `get_nfts_by_owner`, `get_nft_collection_info`
- `security_check_nft`, `transfer_nft`
- `approve_nft`, `set_approval_for_all`
**Conversation Style:** Visual when possible, descriptive, organized
**Example Prompts:**
- "Show my NFTs on Ethereum"
- "Get metadata for BAYC #1234"
- "Is this NFT collection legitimate?"
- "Transfer my NFT to another wallet"
**System Prompt:**
```
You are an NFT Explorer Agent helping users navigate the NFT ecosystem.
Your capabilities include:
- Fetching NFT metadata and traits
- Checking NFT ownership
- Listing NFTs by wallet
- Collection security analysis
- NFT transfers and approvals
NFT Guidelines:
1. Always show the image/media when available
2. List traits and rarity when known
3. Check collection verification status
4. Warn about suspicious collections
5. Verify ownership before transfers
When displaying NFTs:
- Show name, collection, and token ID
- Include trait count and rarity (if available)
- Note the current owner
- Flag any security concerns
Before transfers:
- Verify current ownership
- Confirm recipient address
- Check for existing approvals
```
---
## ⚙️ Agent Configuration Templates
Ready-to-use configurations for major platforms.
### Claude Desktop Configuration
```json
{
"mcpServers": {
"bnbchain-mcp": {
"command": "npx",
"args": ["-y", "@nirholas/bnbchain-mcp@latest"],
"env": {
"PRIVATE_KEY": "your_private_key_optional",
"COINGECKO_API_KEY": "your_key_optional",
"LUNARCRUSH_API_KEY": "your_key_optional"
}
}
}
}
```
### ChatGPT Developer Mode Configuration
1. Start HTTP server:
```bash
npx @nirholas/bnbchain-mcp@latest --http
```
2. In ChatGPT Settings → Apps → Create app
3. Enter URL: `http://localhost:3001/mcp`
### Cursor Configuration
```json
{
"mcpServers": {
"bnbchain-mcp": {
"command": "npx",
"args": ["-y", "@nirholas/bnbchain-mcp@latest"],
"env": {
"PRIVATE_KEY": "${CRYPTO_PRIVATE_KEY}"
}
}
}
}
```
### Full Agent Configuration (Claude Desktop)
```json
{
"mcpServers": {
"bnbchain-mcp": {
"command": "npx",
"args": ["-y", "@nirholas/bnbchain-mcp@latest"],
"env": {
"PRIVATE_KEY": "0x...",
"COINGECKO_API_KEY": "CG-...",
"COINSTATS_API_KEY": "...",
"LUNARCRUSH_API_KEY": "..."
}
}
},
"systemPrompt": "You are a DeFi Analyst Agent specializing in protocol analysis..."
}
```
### Environment Variables Reference
| Variable | Required | Description |
|----------|----------|-------------|
| `PRIVATE_KEY` | For write ops | Wallet private key for transactions |
| `COINGECKO_API_KEY` | Optional | Higher rate limits for market data |
| `COINSTATS_API_KEY` | For portfolio | Portfolio tracking features |
| `LUNARCRUSH_API_KEY` | For social | Social sentiment analysis |
| `CRYPTOCOMPARE_API_KEY` | Optional | Additional social data |
---
## 📊 Agent Capabilities Matrix
| Agent Persona | Read Ops | Write Ops | APIs | Risk Level |
|--------------|----------|-----------|------|------------|
| DeFi Analyst | ✅ All | ❌ None | DefiLlama, CoinGecko | Low |
| Portfolio Manager | ✅ All | ⚠️ Revoke approvals | All | Medium |
| Security Auditor | ✅ All | ❌ None | GoPlus | Low |
| Trading Assistant | ✅ All | ✅ Swaps | DEX APIs | High |
| Market Research | ✅ All | ❌ None | CoinGecko, LunarCrush | Low |
| Cross-Chain Navigator | ✅ All | ✅ Bridge | Bridge APIs | High |
| Governance Participant | ✅ All | ✅ Vote/Delegate | On-chain | Medium |
| NFT Explorer | ✅ All | ⚠️ Transfers | On-chain | Medium |
### Tool Categories by Agent
```
┌─────────────────────┬───────────────────────────────────────────────────────┐
│ Agent │ Primary Tool Categories │
├─────────────────────┼───────────────────────────────────────────────────────┤
│ DeFi Analyst │ defi_*, market_*, analytics_* │
│ Portfolio Manager │ get_balance, get_*_position, security_check_* │
│ Security Auditor │ security_*, detect_*, check_* │
│ Trading Assistant │ get_swap_*, execute_swap, dex_*, gas_* │
│ Market Research │ market_*, social_*, news_* │
│ Cross-Chain Nav │ *_bridge_*, get_chain_*, defi_get_chains │
│ Governance │ governance_* │
│ NFT Explorer │ *_nft_*, get_nfts_* │
└─────────────────────┴───────────────────────────────────────────────────────┘
```
---
## 🔄 Multi-Agent Workflows
### Workflow 1: Portfolio Health Check
**Agents:** Portfolio Manager → Security Auditor → DeFi Analyst
```mermaid
sequenceDiagram
participant User
participant PM as Portfolio Manager
participant SA as Security Auditor
participant DA as DeFi Analyst
User->>PM: Check my portfolio health
PM->>PM: get_wallet_portfolio
PM->>PM: get_lending_position
PM->>SA: Audit token approvals
SA->>SA: security_check_approvals
SA->>SA: Flag risky approvals
SA->>DA: Analyze positions
DA->>DA: Compare yields
DA->>DA: defi_get_yields
DA->>User: Complete health report
```
**Implementation:**
```typescript
// Agent orchestration pseudo-code
async function portfolioHealthCheck(address: string) {
// Phase 1: Portfolio Manager
const portfolio = await agent.call('get_wallet_portfolio', { address });
const positions = await agent.call('get_lending_position', { address });
// Phase 2: Security Auditor
const approvals = await agent.call('security_check_approvals', { address });
const riskyApprovals = approvals.filter(a => a.risk === 'high');
// Phase 3: DeFi Analyst
const yields = await agent.call('defi_get_yields', {
chain: portfolio.primaryChain,
minTvl: 1000000
});
return generateHealthReport(portfolio, positions, riskyApprovals, yields);
}
```
---
### Workflow 2: Smart Token Purchase
**Agents:** Security Auditor → Market Research → Trading Assistant
```mermaid
sequenceDiagram
participant User
participant SA as Security Auditor
participant MR as Market Research
participant TA as Trading Assistant
User->>SA: I want to buy token 0x123
SA->>SA: security_check_token
SA->>SA: detect_honeypot
alt Token is safe
SA->>MR: Analyze market data
MR->>MR: market_get_coin
MR->>MR: social_get_coin_metrics
MR->>TA: Get best swap route
TA->>TA: get_swap_quote
TA->>User: Present quote & analysis
else Token is risky
SA->>User: ⚠️ Security risks detected
end
```
---
### Workflow 3: Yield Optimization
**Agents:** Portfolio Manager → DeFi Analyst → Trading Assistant
```mermaid
sequenceDiagram
participant User
participant PM as Portfolio Manager
participant DA as DeFi Analyst
participant TA as Trading Assistant
User->>PM: Optimize my yield
PM->>PM: Get current positions
PM->>DA: Find better yields
DA->>DA: defi_get_yields
DA->>DA: Compare with current
alt Better yield found
DA->>TA: Calculate swap needed
TA->>TA: get_swap_quote
TA->>User: Recommend reallocation
else Current is optimal
DA->>User: Portfolio already optimized
end
```
---
### Workflow 4: Cross-Chain Arbitrage Scout
**Agents:** DeFi Analyst → Cross-Chain Navigator → Trading Assistant
```mermaid
flowchart TB
A[DeFi Analyst<br/>Find yield differences] --> B{Opportunity<br/>exists?}
B -->|Yes| C[Cross-Chain Navigator<br/>Calculate bridge costs]
C --> D{Profitable after<br/>fees?}
D -->|Yes| E[Trading Assistant<br/>Execute arbitrage]
D -->|No| F[Report: Not profitable]
B -->|No| G[Report: No opportunities]
E --> H[Monitor positions]
```
---
## 🛡️ Safety Guidelines
### Read-Only Operations (Safe)
These tools only read data and cannot affect user funds:
```typescript
const READ_ONLY_TOOLS = [
// Balances
'get_balance', 'get_token_balance', 'get_wallet_portfolio',
// Market Data
'market_get_coins', 'market_get_price', 'market_get_trending',
// DeFi Analytics
'defi_get_protocols', 'defi_get_yields', 'defi_get_chains',
// Security (non-invasive)
'security_check_token', 'detect_honeypot', 'check_rug_risk',
// DEX Quotes (no execution)
'get_swap_quote', 'get_pool_reserves', 'dex_get_network_pools',
// Social/News
'social_get_coin_metrics', 'news_get_latest'
];
```
### Write Operations (Require Confirmation)
These tools can affect user funds and MUST require explicit confirmation:
```typescript
const WRITE_TOOLS = [
// Token Operations
'transfer_token', 'approve_token', 'batch_transfer',
// Trading
'execute_swap',
// Bridging
'execute_bridge',
// Lending
'lending_supply', 'lending_withdraw', 'lending_borrow', 'lending_repay',
// Staking
'stake', 'unstake', 'claim_staking_rewards',
// Governance
'governance_vote', 'governance_delegate',
// NFT
'transfer_nft', 'approve_nft'
];
```
### Address Validation Rules
```typescript
// Always validate addresses before operations
function validateAddress(address: string): boolean {
// Must be valid hex format
if (!/^0x[a-fA-F0-9]{40}$/.test(address)) {
return false;
}
// Check for common scam patterns
const BLACKLISTED = ['0x0000000000000000000000000000000000000000'];
if (BLACKLISTED.includes(address.toLowerCase())) {
return false;
}
return true;
}
```
### Rate Limiting Recommendations
| API | Recommended Limit | Burst Allowed |
|-----|------------------|---------------|
| CoinGecko (free) | 50/min | No |
| CoinGecko (pro) | 500/min | Yes |
| DefiLlama | No limit | Yes |
| GoPlus | 100/min | No |
| LunarCrush (free) | 100/day | No |
| DexPaprika | 100/min | No |
### Error Handling Patterns
```typescript
// Standard error handling for agent tools
async function safeToolCall(toolName: string, params: any) {
try {
const result = await mcpServer.callTool(toolName, params);
return { success: true, data: result };
} catch (error) {
if (error.code === 'RATE_LIMIT') {
return { success: false, error: 'Rate limited. Please try again later.' };
}
if (error.code === 'INSUFFICIENT_FUNDS') {
return { success: false, error: 'Insufficient balance for this operation.' };
}
if (error.code === 'USER_REJECTED') {
return { success: false, error: 'Transaction rejected by user.' };
}
return { success: false, error: error.message };
}
}
```
---
## 🔌 Framework Integration
### LangChain Integration
```python
from langchain_community.tools import MCPToolkit
from langchain.agents import AgentExecutor, create_openai_functions_agent
from langchain_openai import ChatOpenAI
# Initialize MCP connection
mcp_toolkit = MCPToolkit(
server_command="npx",
server_args=["-y", "@nirholas/bnbchain-mcp@latest"],
env={
"PRIVATE_KEY": os.getenv("CRYPTO_PRIVATE_KEY"),
"COINGECKO_API_KEY": os.getenv("COINGECKO_API_KEY")
}
)
# Get tools from MCP server
tools = mcp_toolkit.get_tools()
# Create agent with DeFi Analyst persona
llm = ChatOpenAI(model="gpt-4", temperature=0)
system_prompt = """You are a DeFi Analyst Agent specializing in protocol analysis.
Use the available tools to fetch real data. Never make up numbers.
Always compare multiple data points for context."""
agent = create_openai_functions_agent(llm, tools, system_prompt)
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)
# Run agent
result = agent_executor.invoke({
"input": "What are the top 5 yield opportunities on Arbitrum with TVL > $1M?"
})
```
### AutoGPT Integration
```yaml
# autogpt_config.yaml
ai_settings:
ai_name: DeFi-Analyst-GPT
ai_role: A DeFi analyst that helps users find yield opportunities and analyze protocols
ai_goals:
- Analyze DeFi protocols for yield opportunities
- Monitor portfolio health and positions
- Provide security analysis for tokens
- Track market trends and sentiment
plugins:
- name: bnbchain-mcp
command: npx
args:
- "-y"
- "@nirholas/bnbchain-mcp@latest"
env:
COINGECKO_API_KEY: "${COINGECKO_API_KEY}"
```
### CrewAI Integration
```python
from crewai import Agent, Task, Crew
from crewai_tools import MCPTool
# Create MCP tools
mcp_defi = MCPTool(
name="DeFi Analytics",
server_command="npx @nirholas/bnbchain-mcp@latest",
tools=["defi_get_protocols", "defi_get_yields", "defi_get_fees"]
)
mcp_security = MCPTool(
name="Security Analysis",
server_command="npx @nirholas/bnbchain-mcp@latest",
tools=["security_check_token", "detect_honeypot", "check_rug_risk"]
)
# Create specialized agents
defi_analyst = Agent(
role="DeFi Analyst",
goal="Analyze DeFi protocols and find yield opportunities",
backstory="Expert in DeFi protocol analysis with deep knowledge of yield farming",
tools=[mcp_defi],
verbose=True
)
security_auditor = Agent(
role="Security Auditor",
goal="Analyze tokens and contracts for security risks",
backstory="Security expert specializing in smart contract and token analysis",
tools=[mcp_security],
verbose=True
)
# Define tasks
analysis_task = Task(
description="Find the top 5 yield opportunities on {chain} with TVL > $1M",
agent=defi_analyst
)
security_task = Task(
description="Verify the security of tokens found in the yield opportunities",
agent=security_auditor,
context=[analysis_task]
)
# Create crew
crew = Crew(
agents=[defi_analyst, security_auditor],
tasks=[analysis_task, security_task],
verbose=2
)
# Run
result = crew.kickoff(inputs={"chain": "Arbitrum"})
```
### Custom Framework Integration
```typescript
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
class CryptoAgent {
private client: Client;
async initialize() {
const transport = new StdioClientTransport({
command: "npx",
args: ["-y", "@nirholas/bnbchain-mcp@latest"],
env: {
COINGECKO_API_KEY: process.env.COINGECKO_API_KEY,
}
});
this.client = new Client({
name: "crypto-agent",
version: "1.0.0"
}, {
capabilities: {}
});
await this.client.connect(transport);
}
async getYields(chain: string, minApy: number = 5) {
const result = await this.client.callTool({
name: "defi_get_yields",
arguments: { chain, minApy }
});
return JSON.parse(result.content[0].text);
}
async checkTokenSafety(network: string, tokenAddress: string) {
const [security, honeypot] = await Promise.all([
this.client.callTool({
name: "security_check_token",
arguments: { network, tokenAddress }
}),
this.client.callTool({
name: "detect_honeypot",
arguments: { network, tokenAddress }
})
]);
return {
security: JSON.parse(security.content[0].text),
honeypot: JSON.parse(honeypot.content[0].text)
};
}
}
// Usage
const agent = new CryptoAgent();
await agent.initialize();
const yields = await agent.getYields("Arbitrum", 10);
console.log("Top yields:", yields);
```
---
## 🧪 Testing Guide
### MCP Inspector Usage
Test tools interactively with MCP Inspector:
```bash
# Install MCP Inspector
npm install -g @anthropic-ai/mcp-inspector
# Start BNB Chain MCP server
npx @nirholas/bnbchain-mcp@latest &
# Connect Inspector
mcp-inspector stdio -- npx @nirholas/bnbchain-mcp@latest
```
### Test Cases
#### Basic Connectivity Test
```typescript
// Test: Server responds to tool list request
const tools = await client.listTools();
expect(tools.length).toBeGreaterThan(100);
```
#### Market Data Test
```typescript
// Test: Can fetch Bitcoin price
const result = await client.callTool({
name: "market_get_price",
arguments: { ids: ["bitcoin"], vsCurrencies: ["usd"] }
});
const data = JSON.parse(result.content[0].text);
expect(data.bitcoin.usd).toBeGreaterThan(0);
```
#### DeFi Data Test
```typescript
// Test: Can fetch protocol TVL
const result = await client.callTool({
name: "defi_get_protocol",
arguments: { protocol: "aave" }
});
const data = JSON.parse(result.content[0].text);
expect(data.tvl).toBeGreaterThan(0);
expect(data.chains).toContain("Ethereum");
```
#### Security Check Test
```typescript
// Test: Can detect honeypot (use known honeypot)
const result = await client.callTool({
name: "detect_honeypot",
arguments: {
network: "bsc",
tokenAddress: "0x..." // Known honeypot
}
});
const data = JSON.parse(result.content[0].text);
expect(data.isHoneypot).toBe(true);
```
### Mock Data for Testing
```typescript
// Mock responses for testing without API calls
const MOCK_DATA = {
market_get_price: {
bitcoin: { usd: 50000, usd_24h_change: 2.5 },
ethereum: { usd: 3000, usd_24h_change: -1.2 }
},
defi_get_yields: {
data: [
{ pool: "USDC-USDT", chain: "Ethereum", apy: 5.5, tvlUsd: 10000000 },
{ pool: "ETH-USDC", chain: "Arbitrum", apy: 12.3, tvlUsd: 5000000 }
]
},
security_check_token: {
isHoneypot: false,
buyTax: "0%",
sellTax: "0%",
riskLevel: "low"
}
};
```
### Performance Benchmarks
| Operation | Expected Time | Max Acceptable |
|-----------|--------------|----------------|
| Market price lookup | <500ms | 2s |
| DeFi protocol data | <1s | 3s |
| Security check | <2s | 5s |
| Swap quote | <3s | 10s |
| Bridge quote | <5s | 15s |
---
## 📚 Additional Resources
- **GitHub Repository:** https://github.com/nirholas/bnbchain-mcp
- **Documentation:** https://bnbchain-mcp.vercel.app
- **MCP Specification:** https://modelcontextprotocol.io
- **Skills Reference:** [SKILLS.md](./SKILLS.md)
---
## 📜 License
Apache-2.0 License - Built by **[nich](https://x.com/nichxbt)**
