Binance MCP Server

binance-mcp
instructions
# Binance MCP Server - API Implementation Status

## Overview

This document provides a comprehensive summary of the Binance API integration status in the MCP server, detailing which endpoints have been implemented, what's newly added, and what's planned for future development.

## Current Implementation Status

### REST API Implementation

| API Category | Endpoint | Status | Implementation |
|--------------|----------|--------|----------------|
| **Market Data** | GET /api/v3/ticker/price | ✅ Implemented | `get_price()` in market_data.py |
| **Market Data** | GET /api/v3/depth | ✅ Implemented | `get_order_book()` in market_data.py |
| **Market Data** | GET /api/v3/klines | ✅ Implemented | `get_historical_prices()` in market_data.py |
| **Market Data** | GET /api/v3/exchangeInfo | ✅ Implemented | `get_exchange_info()` in market_info.py |
| **Market Data** | GET /api/v3/trades | ✅ Implemented | `get_recent_trades()` in market_data.py |
| **Market Data** | GET /api/v3/aggTrades | ✅ Implemented | `get_aggregate_trades()` in market_data.py |
| **Market Data** | GET /api/v3/ticker/24hr | ✅ Implemented | `get_24hr_ticker()` in market_data.py |
| **Market Data** | GET /api/v3/avgPrice | ✅ Implemented | `get_average_price()` in market_data.py |
| **Market Data** | GET /api/v3/ticker/bookTicker | ✅ Implemented | `get_book_ticker()` in market_data.py |
| **Market Data** | GET /api/v3/ping | ✅ Implemented | `ping_binance()` in market_data.py |
| **Market Data** | GET /api/v3/time | ✅ Implemented | `get_server_time()` in market_data.py |
| **Market Data** | GET /api/v3/historicalTrades | ✅ Implemented | `get_historical_trades()` in market_data.py |
| **Market Data** | GET /api/v3/uiKlines | ✅ Implemented | `get_ui_klines()` in market_data.py |
| **Market Data** | GET /api/v3/ticker/tradingDay | ✅ Implemented | `get_trading_day_ticker()` in market_data.py |
| **Market Data** | GET /api/v3/ticker | ✅ Implemented | `get_rolling_window_ticker()` in market_data.py |
| **Trading** | POST /api/v3/order | ❌ Not Implemented | - |
| **Trading** | POST /api/v3/order/test | ❌ Not Implemented | - |
| **Trading** | GET /api/v3/order | ❌ Not Implemented | - |
| **Trading** | DELETE /api/v3/order | ❌ Not Implemented | - |
| **Account** | GET /api/v3/account | ❌ Not Implemented | - |
| **Account** | GET /api/v3/myTrades | ❌ Not Implemented | - |
| **User Data Stream** | POST /api/v3/userDataStream | ❌ Not Implemented | - |
| **User Data Stream** | PUT /api/v3/userDataStream | ❌ Not Implemented | - |
| **User Data Stream** | DELETE /api/v3/userDataStream | ❌ Not Implemented | - |

### WebSocket Implementation

| Stream Type | Description | Status | Implementation |
|-------------|-------------|--------|----------------|
| Trade Stream | Real-time trades for a symbol | ✅ Implemented | `subscribe_to_trade_stream()` in websocket_streams.py |
| Kline Stream | Real-time candlestick data | ✅ Implemented | `subscribe_to_kline_stream()` in websocket_streams.py |
| Ticker Stream | 24hr ticker updates | ✅ Implemented | `subscribe_to_ticker_stream()` in websocket_streams.py |
| Book Ticker Stream | Best bid/ask updates | ✅ Implemented | `subscribe_to_book_ticker_stream()` in websocket_streams.py |
| Depth Stream | Order book updates | ✅ Implemented | `subscribe_to_depth_stream()` in websocket_streams.py |
| All Market Tickers | All symbols ticker | ❌ Not Implemented | - |
| All Market Mini-Tickers | All symbols mini ticker | ❌ Not Implemented | - |
| User Data Stream | Account/order updates | ❌ Not Implemented | - |

## Recent Additions

In this update, the following API endpoints and capabilities were added:

### New REST API Endpoints

1. **Server Status** - `ping_binance()`: Tests connectivity to the Binance API server.
2. **Server Time** - `get_server_time()`: Gets the current server time from Binance.
3. **Historical Trades** - `get_historical_trades(symbol, limit, from_id)`: Retrieves older trade data with optional pagination.
4. **UI Klines** - `get_ui_klines(symbol, interval, limit)`: Fetches UI-optimized candlestick data.
5. **Trading Day Ticker** - `get_trading_day_ticker(symbol, type)`: Gets statistics for the current trading day.
6. **Rolling Window Ticker** - `get_rolling_window_ticker(symbol, window_size, type)`: Gets statistics for a specific rolling window period.

### Previous Additions

1. **Recent Trades** - `get_recent_trades(symbol, limit)`: Retrieves the most recent trades for a specific symbol.
2. **Aggregate Trades** - `get_aggregate_trades(symbol, limit)`: Fetches a compressed view of trades that occurred at the same price.
3. **24hr Ticker** - `get_24hr_ticker(symbol)`: Gets 24-hour price change statistics for a specific symbol.
4. **Average Price** - `get_average_price(symbol)`: Retrieves the current average price for a symbol based on the last 5 minutes of trades.
5. **Book Ticker** - `get_book_ticker(symbol)`: Gets the best bid and ask prices/quantities for a symbol.

### WebSocket Integration

A complete WebSocket API framework was implemented, including:

1. **WebSocket Connection Management**:
   - Connection handling with automatic ping/pong responses
   - Subscription and unsubscription functionality
   - Message processing pipeline

2. **Market Data WebSocket Streams**:
   - Trade streams for real-time trade data
   - Kline/candlestick streams for real-time chart data
   - Ticker streams for 24hr price statistics
   - Book ticker streams for best bid/ask updates
   - Depth streams for order book updates

3. **WebSocket Command Integration**:
   - Management tools for listing active streams
   - Retrieving latest stream data
   - Cleaning up resources

## Future Implementation Roadmap

The following enhancements are planned for future development:

### Short-term Priorities

1. **Authenticated REST APIs**:
   - Account information
   - Order placement and management
   - Trade history

2. **User Data Streams**:
   - Listen key management
   - Account update subscriptions
   - Order update subscriptions

### Medium-term Priorities

1. **Advanced Order Types**:
   - OCO (One-Cancels-the-Other) orders
   - Order lists (OTO, OTOCO)
   - Stop-loss and take-profit orders

2. **Additional WebSocket Streams**:
   - All market tickers stream
   - Mini-ticker streams
   - Diff. depth stream

### Long-term Priorities

1. **Performance Optimization**:
   - Connection pooling for REST API
   - Efficient WebSocket message handling
   - Local data caching for frequent queries

2. **Security Enhancements**:
   - Multiple API key management
   - Support for different API key types (HMAC, RSA, Ed25519)
   - Rate limit monitoring and throttling

## Using the API in the MCP Server

### REST API Example

```python
# Basic connectivity and information
is_connected = ping_binance()
server_time = get_server_time()

# Market data retrieval
symbol_price = get_price("BTCUSDT")
recent_trades = get_recent_trades("ETHBTC", limit=50)
ticker_data = get_24hr_ticker("BNBUSDT")

# Advanced market data
historical_trades = get_historical_trades("BTCUSDT", limit=100, from_id=12345)
ui_optimized_klines = get_ui_klines("ETHUSDT", interval="4h", limit=50)
rolling_stats = get_rolling_window_ticker("BTCUSDT", window_size="4h")
```

### WebSocket API Example

```python
# Subscribe to a WebSocket stream:
subscription = subscribe_to_trade_stream("BTCUSDT")

# Get the latest data from a stream:
latest_data = get_latest_stream_data("btcusdt@trade")

# List all active subscriptions:
subscriptions = list_active_subscriptions()

# Unsubscribe when done:
unsubscribe_from_stream("btcusdt@trade")
```

## Dependencies

- requests: For REST API calls
- websockets: For WebSocket connections
- mcp: The Model Context Protocol SDK
- uvicorn: ASGI server implementation 