API Reference¶
This document provides comprehensive documentation for all 17 tools available in the Binance MCP Server.
Response Format¶
All tools return a standardized response format:
Success Response¶
{
"success": true,
"data": { /* Tool-specific data */ },
"timestamp": 1704067200000,
"metadata": {
"source": "binance_api",
"endpoint": "tool_name"
}
}
Error Response¶
{
"success": false,
"error": {
"type": "error_type",
"message": "Human-readable error message",
"timestamp": 1704067200000
}
}
Market Data Tools¶
get_ticker_price¶
Get the current price for a trading symbol.
Parameters:
- symbol (string, required): Trading pair symbol (e.g., 'BTCUSDT', 'ETHBTC')
Example:
Response:
{
"success": true,
"data": {
"symbol": "BTCUSDT",
"price": 42350.50
},
"timestamp": 1704067200000,
"metadata": {
"source": "binance_api",
"endpoint": "ticker_price"
}
}
get_ticker¶
Get 24-hour ticker price change statistics for a symbol.
Parameters:
- symbol (string, required): Trading pair symbol (e.g., 'BTCUSDT', 'ETHUSDT')
Example:
Response:
{
"success": true,
"data": {
"symbol": "BTCUSDT",
"priceChange": "125.50",
"priceChangePercent": "0.297",
"weightedAvgPrice": "42280.15",
"prevClosePrice": "42225.00",
"lastPrice": "42350.50",
"lastQty": "0.001",
"bidPrice": "42350.00",
"bidQty": "1.5",
"askPrice": "42350.50",
"askQty": "2.1",
"openPrice": "42225.00",
"highPrice": "42450.00",
"lowPrice": "41800.00",
"volume": "1234.567",
"quoteVolume": "52234567.89",
"openTime": 1704067200000,
"closeTime": 1704153600000,
"count": 123456
},
"timestamp": 1704067200000
}
get_order_book¶
Get the current order book (bids/asks) for a trading symbol.
Parameters:
- symbol (string, required): Trading pair symbol (e.g., 'BTCUSDT', 'ETHBTC')
- limit (integer, optional): Number of orders per side (default: 100, max: 5000)
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"]
],
"bidCount": 3,
"askCount": 3,
"lastUpdateId": 123456789
},
"timestamp": 1704067200000
}
get_available_assets¶
Get a list of all available trading symbols and their information.
Parameters: None
Example:
Response:
{
"success": true,
"data": {
"assets": {
"BTCUSDT": {
"symbol": "BTCUSDT",
"status": "TRADING",
"baseAsset": "BTC",
"baseAssetPrecision": 8,
"quoteAsset": "USDT",
"quotePrecision": 8,
"quoteAssetPrecision": 8,
"orderTypes": ["LIMIT", "LIMIT_MAKER", "MARKET", "STOP_LOSS_LIMIT", "TAKE_PROFIT_LIMIT"],
"icebergAllowed": true,
"ocoAllowed": true,
"isSpotTradingAllowed": true,
"isMarginTradingAllowed": true,
"filters": [...]
}
},
"count": 2000
},
"timestamp": 1704067200000
}
Account Management Tools¶
get_balance¶
Get the current account balance for all assets.
Parameters: None
Example:
Response:
{
"success": true,
"data": {
"BTC": {
"free": 0.12345678,
"locked": 0.0
},
"USDT": {
"free": 1234.56,
"locked": 100.0
},
"ETH": {
"free": 2.5,
"locked": 0.5
}
},
"timestamp": 1704067200000
}
get_account_snapshot¶
Get a point-in-time snapshot of account state.
Parameters:
- account_type (string, optional): Account type (default: "SPOT", options: "SPOT", "MARGIN", "FUTURES")
Example:
Response:
{
"success": true,
"data": {
"code": 200,
"msg": "",
"snapshotVos": [
{
"data": {
"balances": [
{
"asset": "BTC",
"free": "0.12345678",
"locked": "0.00000000"
}
],
"totalAssetOfBtc": "0.12345678"
},
"type": "spot",
"updateTime": 1704067200000
}
]
},
"timestamp": 1704067200000
}
get_position_info¶
Get current position information for futures trading.
Parameters: None
Example:
Response:
{
"success": true,
"data": [
{
"symbol": "BTCUSDT",
"positionAmt": "0.001",
"entryPrice": "42000.0",
"markPrice": "42350.50",
"unRealizedProfit": "0.3505",
"liquidationPrice": "0",
"leverage": "10",
"maxNotionalValue": "25000",
"marginType": "isolated",
"isolatedMargin": "42.00000000",
"isAutoAddMargin": "false",
"positionSide": "BOTH",
"notional": "42.3505",
"isolatedWallet": "42.00000000",
"updateTime": 1704067200000
}
],
"timestamp": 1704067200000
}
get_pnl¶
Get profit and loss (PnL) information for futures trading.
Parameters: None
Example:
Response:
{
"success": true,
"data": [
{
"symbol": "BTCUSDT",
"income": "12.34567890",
"incomeType": "REALIZED_PNL",
"asset": "USDT",
"time": 1704067200000,
"info": "BTCUSDT",
"tranId": 9876543210,
"tradeId": "123456789"
}
],
"timestamp": 1704067200000
}
Trading Tools¶
create_order¶
Create a new trading order.
Parameters:
- symbol (string, required): Trading pair symbol (e.g., 'BTCUSDT')
- side (string, required): Order side ('BUY' or 'SELL')
- order_type (string, required): Order type ('LIMIT', 'MARKET', 'STOP_LOSS', etc.)
- quantity (float, required): Quantity of the asset to buy/sell
- price (float, optional): Price for limit orders
Example:
{
"tool": "create_order",
"arguments": {
"symbol": "BTCUSDT",
"side": "BUY",
"order_type": "LIMIT",
"quantity": 0.001,
"price": 42000.0
}
}
Response:
{
"success": true,
"data": {
"symbol": "BTCUSDT",
"orderId": 123456789,
"orderListId": -1,
"clientOrderId": "abc123",
"transactTime": 1704067200000,
"price": "42000.00000000",
"origQty": "0.00100000",
"executedQty": "0.00000000",
"cummulativeQuoteQty": "0.00000000",
"status": "NEW",
"timeInForce": "GTC",
"type": "LIMIT",
"side": "BUY",
"fills": []
},
"timestamp": 1704067200000
}
get_orders¶
Get order history for a specific symbol.
Parameters:
- symbol (string, required): Trading pair symbol (e.g., 'BTCUSDT', 'ETHUSDT')
- start_time (integer, optional): Start time for filtering orders (Unix timestamp in ms)
- end_time (integer, optional): End time for filtering orders (Unix timestamp in ms)
Example:
{
"tool": "get_orders",
"arguments": {
"symbol": "BTCUSDT",
"start_time": 1704000000000,
"end_time": 1704086400000
}
}
Response:
{
"success": true,
"data": [
{
"symbol": "BTCUSDT",
"orderId": 123456789,
"orderListId": -1,
"clientOrderId": "abc123",
"price": "42000.00000000",
"origQty": "0.00100000",
"executedQty": "0.00100000",
"cummulativeQuoteQty": "42.00000000",
"status": "FILLED",
"timeInForce": "GTC",
"type": "LIMIT",
"side": "BUY",
"stopPrice": "0.00000000",
"icebergQty": "0.00000000",
"time": 1704067200000,
"updateTime": 1704067250000,
"isWorking": true,
"origQuoteOrderQty": "0.00000000"
}
],
"timestamp": 1704067200000
}
Transaction History Tools¶
get_deposit_history¶
Get deposit history for a specific coin.
Parameters:
- coin (string, required): The coin for which to fetch deposit history (e.g., 'BTC', 'ETH')
Example:
Response:
{
"success": true,
"data": [
{
"amount": "0.12345678",
"coin": "BTC",
"network": "BTC",
"status": 1,
"address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
"addressTag": "",
"txId": "abc123def456",
"insertTime": 1704067200000,
"transferType": 0,
"confirmTimes": "1/1"
}
],
"timestamp": 1704067200000
}
get_withdraw_history¶
Get withdrawal history for a specific coin.
Parameters:
- coin (string, required): The coin for which to fetch withdrawal history (e.g., 'BTC', 'ETH')
Example:
Response:
{
"success": true,
"data": [
{
"address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
"amount": "0.05000000",
"applyTime": "2024-01-01 12:00:00",
"coin": "BTC",
"id": "abc123def456",
"withdrawOrderId": "def456ghi789",
"network": "BTC",
"transferType": 0,
"status": 6,
"transactionFee": "0.0005",
"confirmNo": 3,
"info": "Withdrawal completed",
"txId": "ghi789jkl012"
}
],
"timestamp": 1704067200000
}
get_deposit_address¶
Get deposit address for a specific coin.
Parameters:
- coin (string, required): The coin for which to fetch the deposit address (e.g., 'BTC', 'ETH')
Example:
Response:
{
"success": true,
"data": {
"address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
"coin": "BTC",
"tag": "",
"url": "https://btc.com/1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"
},
"timestamp": 1704067200000
}
get_liquidation_history¶
Get liquidation history for futures trading.
Parameters: None
Example:
Response:
{
"success": true,
"data": [
{
"symbol": "BTCUSDT",
"price": "40000.00",
"origQty": "0.001",
"executedQty": "0.001",
"avrPrice": "40000.00",
"status": "FILLED",
"timeInForce": "IOC",
"type": "LIMIT",
"side": "SELL",
"time": 1704067200000
}
],
"timestamp": 1704067200000
}
get_universal_transfer_history¶
Get universal transfer history (transfers between different account types).
Parameters: None
Example:
Response:
{
"success": true,
"data": {
"message": "This feature is currently under development"
},
"timestamp": 1704067200000
}
Fee Information Tools¶
get_fee_info¶
Get trading fee information for symbols.
Parameters:
- symbol (string, optional): Specific trading pair symbol. If not provided, returns fees for all symbols
Example:
Response:
{
"success": true,
"data": [
{
"symbol": "BTCUSDT",
"makerCommission": "0.001",
"takerCommission": "0.001"
}
],
"timestamp": 1704067200000,
"metadata": {
"source": "binance_api",
"endpoint": "trade_fee"
}
}
Error Types¶
The API can return the following error types:
validation_error¶
Parameter validation failed (invalid symbol format, missing required parameters, etc.)
binance_api_error¶
Error from Binance API (invalid API key, insufficient balance, rate limits, etc.)
rate_limit_exceeded¶
API rate limit has been exceeded, retry after waiting
tool_error¶
Unexpected error during tool execution
network_error¶
Network connectivity issues or timeouts
Rate Limiting¶
All tools are subject to Binance API rate limits: - 1200 requests per minute for most endpoints - 10 requests per second burst limit - Rate limiting is handled automatically by the server
When rate limits are exceeded, you'll receive a rate_limit_exceeded error. Wait a few seconds before retrying.
Best Practices¶
- Always check the
successfield before processing data - Handle errors gracefully with appropriate fallback logic
- Use testnet (
BINANCE_TESTNET=true) for development - Respect rate limits - avoid making too many requests too quickly
- Validate symbols before making requests to avoid API errors
- Log responses for debugging and monitoring