Usage Examples¶

This guide provides practical examples of using the Binance MCP Server tools in various scenarios.

Getting Started Examples¶

Basic Market Data¶

Get Current Bitcoin Price¶

{
  "tool": "get_ticker_price",
  "arguments": {
    "symbol": "BTCUSDT"
  }
}

Response:

{
  "success": true,
  "data": {
    "symbol": "BTCUSDT",
    "price": 42350.50
  },
  "timestamp": 1704067200000
}

Get 24-Hour Market Statistics¶

{
  "tool": "get_ticker",
  "arguments": {
    "symbol": "ETHUSDT"
  }
}

Use case: Track daily performance, price changes, and trading volume.

Trading Examples¶

Placing Orders¶

Market Buy Order¶

{
  "tool": "create_order",
  "arguments": {
    "symbol": "BTCUSDT",
    "side": "BUY",
    "order_type": "MARKET",
    "quantity": 0.001
  }
}

Use case: Buy Bitcoin immediately at current market price.

Limit Sell Order¶

{
  "tool": "create_order",
  "arguments": {
    "symbol": "ETHUSDT",
    "side": "SELL",
    "order_type": "LIMIT",
    "quantity": 0.5,
    "price": 2500.00
  }
}

Use case: Sell Ethereum when price reaches $2,500.

Order Management¶

Check Order History¶

{
  "tool": "get_orders",
  "arguments": {
    "symbol": "BTCUSDT",
    "start_time": 1704000000000,
    "end_time": 1704086400000
  }
}

Use case: Review all Bitcoin trades from the last 24 hours.

Portfolio Management Examples¶

Account Monitoring¶

Check All Balances¶

{
  "tool": "get_balance",
  "arguments": {}
}

Example Response:

{
  "success": true,
  "data": {
    "BTC": {"free": 0.12345678, "locked": 0.0},
    "ETH": {"free": 2.5, "locked": 0.5},
    "USDT": {"free": 1234.56, "locked": 100.0}
  }
}

Use case: Monitor portfolio composition and available funds.

Get Account Snapshot¶

{
  "tool": "get_account_snapshot",
  "arguments": {
    "account_type": "SPOT"
  }
}

Use case: Generate portfolio reports and track account performance over time.

Futures Trading¶

Check Positions¶

{
  "tool": "get_position_info",
  "arguments": {}
}

Use case: Monitor open futures positions, leverage, and liquidation prices.

Check P&L¶

{
  "tool": "get_pnl",
  "arguments": {}
}

Use case: Track realized and unrealized profits/losses.

Market Analysis Examples¶

Order Book Analysis¶

Get Market Depth¶

{
  "tool": "get_order_book",
  "arguments": {
    "symbol": "BTCUSDT",
    "limit": 20
  }
}

Example Response:

{
  "success": true,
  "data": {
    "symbol": "BTCUSDT",
    "bids": [
      ["42350.00", "1.5"],
      ["42349.50", "2.1"],
      ["42349.00", "0.8"]
    ],
    "asks": [
      ["42350.50", "2.1"],
      ["42351.00", "1.8"],
      ["42351.50", "3.2"]
    ]
  }
}

Use case: Analyze market liquidity and find optimal entry/exit points.

Trading Pair Discovery¶

List Available Assets¶

{
  "tool": "get_available_assets",
  "arguments": {}
}

Use case: Discover new trading pairs and verify symbol formats.

Transaction History Examples¶

Deposit Tracking¶

Check Bitcoin Deposits¶

{
  "tool": "get_deposit_history",
  "arguments": {
    "coin": "BTC"
  }
}

Use case: Verify incoming Bitcoin transfers and deposit confirmations.

Get Deposit Address¶

{
  "tool": "get_deposit_address",
  "arguments": {
    "coin": "ETH"
  }
}

Use case: Generate deposit address for receiving Ethereum.

Withdrawal Monitoring¶

Check Withdrawal Status¶

{
  "tool": "get_withdraw_history",
  "arguments": {
    "coin": "USDT"
  }
}

Use case: Track outgoing USDT transfers and withdrawal status.

Fee Analysis Examples¶

Trading Cost Calculation¶

Get Trading Fees¶

{
  "tool": "get_fee_info",
  "arguments": {
    "symbol": "BTCUSDT"
  }
}

Example Response:

{
  "success": true,
  "data": [
    {
      "symbol": "BTCUSDT",
      "makerCommission": "0.001",
      "takerCommission": "0.001"
    }
  ]
}

Use case: Calculate trading costs and optimize order types (maker vs taker).

Advanced Scenarios¶

Automated Trading Bot¶

Here's an example workflow for a simple trading bot:

1. Check Market Conditions¶

{
  "tool": "get_ticker",
  "arguments": {"symbol": "BTCUSDT"}
}

2. Analyze Order Book¶

{
  "tool": "get_order_book", 
  "arguments": {"symbol": "BTCUSDT", "limit": 10}
}

3. Check Available Balance¶

{
  "tool": "get_balance",
  "arguments": {}
}

4. Place Strategic Order¶

{
  "tool": "create_order",
  "arguments": {
    "symbol": "BTCUSDT",
    "side": "BUY",
    "order_type": "LIMIT",
    "quantity": 0.001,
    "price": 42000.0
  }
}

5. Monitor Order Status¶

{
  "tool": "get_orders",
  "arguments": {"symbol": "BTCUSDT"}
}

Portfolio Rebalancing¶

1. Get Current Portfolio¶

{
  "tool": "get_balance",
  "arguments": {}
}

2. Check Current Prices¶

{
  "tool": "get_ticker_price",
  "arguments": {"symbol": "BTCUSDT"}
}

{
  "tool": "get_ticker_price", 
  "arguments": {"symbol": "ETHUSDT"}
}

3. Calculate Rebalancing Trades¶

Based on portfolio percentages and current values.

4. Execute Rebalancing Orders¶

{
  "tool": "create_order",
  "arguments": {
    "symbol": "BTCUSDT",
    "side": "SELL",
    "order_type": "MARKET",
    "quantity": 0.01
  }
}

Risk Management¶

1. Monitor Futures Positions¶

{
  "tool": "get_position_info",
  "arguments": {}
}

2. Check Liquidation History¶

{
  "tool": "get_liquidation_history",
  "arguments": {}
}

3. Set Stop-Loss Orders¶

{
  "tool": "create_order",
  "arguments": {
    "symbol": "BTCUSDT",
    "side": "SELL",
    "order_type": "STOP_LOSS_LIMIT",
    "quantity": 0.001,
    "price": 40000.0
  }
}

Error Handling Examples¶

Handling API Errors¶

# Example error response
{
  "success": false,
  "error": {
    "type": "binance_api_error",
    "message": "Insufficient balance",
    "timestamp": 1704067200000
  }
}

Common errors and solutions:

Insufficient Balance
Check balance before placing orders
Adjust order quantity
Invalid Symbol
Verify symbol format (e.g., "BTCUSDT" not "BTC/USDT")
Check available assets list
Rate Limit Exceeded
Wait before retrying
Implement exponential backoff

Validation Examples¶

Symbol Validation¶

// ✅ Correct
{"symbol": "BTCUSDT"}

// ❌ Incorrect 
{"symbol": "BTC/USDT"}
{"symbol": "btcusdt"}

Order Side Validation¶

// ✅ Correct
{"side": "BUY"}
{"side": "SELL"}

// ❌ Incorrect
{"side": "buy"}
{"side": "Buy"}

Integration Examples¶

Claude Desktop Integration¶

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "binance": {
      "command": "binance-mcp-server",
      "args": [],
      "env": {
        "BINANCE_API_KEY": "your_key",
        "BINANCE_API_SECRET": "your_secret",
        "BINANCE_TESTNET": "true"
      }
    }
  }
}

Python Integration¶

import requests
import json

# Start server in HTTP mode for testing
# binance-mcp-server --transport streamable-http

def call_tool(tool_name, arguments):
    url = "http://localhost:8000/call"
    payload = {
        "tool": tool_name,
        "arguments": arguments
    }
    response = requests.post(url, json=payload)
    return response.json()

# Get Bitcoin price
result = call_tool("get_ticker_price", {"symbol": "BTCUSDT"})
if result["success"]:
    print(f"BTC Price: ${result['data']['price']}")

cURL Examples¶

# Get current price
curl -X POST http://localhost:8000/call \
  -H "Content-Type: application/json" \
  -d '{"tool": "get_ticker_price", "arguments": {"symbol": "BTCUSDT"}}'

# Check balance
curl -X POST http://localhost:8000/call \
  -H "Content-Type: application/json" \
  -d '{"tool": "get_balance", "arguments": {}}'

# Place order
curl -X POST http://localhost:8000/call \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "create_order",
    "arguments": {
      "symbol": "BTCUSDT",
      "side": "BUY", 
      "order_type": "LIMIT",
      "quantity": 0.001,
      "price": 42000.0
    }
  }'

Best Practices¶

1. Always Use Testnet First¶

export BINANCE_TESTNET="true"

2. Check Success Before Processing¶

if result["success"]:
    data = result["data"]
    # Process data
else:
    error = result["error"]
    # Handle error

3. Implement Retry Logic¶

import time

def retry_tool_call(tool_name, arguments, max_retries=3):
    for attempt in range(max_retries):
        result = call_tool(tool_name, arguments)

        if result["success"]:
            return result

        if result["error"]["type"] == "rate_limit_exceeded":
            time.sleep(2 ** attempt)  # Exponential backoff
            continue

        return result  # Non-retryable error

4. Validate Inputs¶

def validate_symbol(symbol):
    if not symbol or len(symbol) < 3:
        raise ValueError("Invalid symbol")
    return symbol.upper()

5. Monitor Rate Limits¶

Don't exceed 1200 requests per minute
Implement request queuing for high-frequency applications
Use rate limit headers if available

These examples provide a comprehensive foundation for building cryptocurrency trading applications, portfolio management tools, and market analysis systems using the Binance MCP Server.