Binance.US MCP Server
A Model Context Protocol (MCP) server for interacting with the Binance.US cryptocurrency exchange API.
Overview
This MCP server provides programmatic access to Binance.US exchange features including:
- Market Data: Real-time prices, order books, trade history
- Spot Trading: Place, cancel, and manage orders
- Wallet Management: Deposits, withdrawals, balances
- Account Information: Account details, trade history
- Staking: Earn rewards on supported assets
- OTC Trading: Over-the-counter trading
- Sub-Accounts: Manage sub-accounts
- Custodial Solution: For custody partners (requires special API key)
- Credit Line: For institutional credit (requires special API key)
Binance.US vs Binance.com
This server is specifically designed for Binance.US, which differs from Binance.com in several important ways:
| Feature | Binance.US | Binance.com |
|---|---|---|
| Base URL | api.binance.us | api.binance.com |
| WebSocket | stream.binance.us:9443 | stream.binance.com:9443 |
| Regulation | US SEC/FinCEN compliant | International |
| Futures Trading | ❌ Not available | ✅ Available |
| Margin Trading | ❌ Not available | ✅ Available |
| Lending | ❌ Not available | ✅ Available |
| Custodial Solution API | ✅ Available | ❌ Not available |
| Credit Line API | ✅ Available | ❌ Not available |
| Available Pairs | ~150 pairs | ~1,500+ pairs |
API Key Types
Binance.US offers three types of API keys:
1. Exchange API Keys
- Standard API keys for most users
- Access to market data, trading, wallet, and account endpoints
- Create at: Binance.US > Profile > API Management
2. Custodial Solution API Keys
- For users with a Custody Exchange Network agreement
- Access to custodial-specific endpoints only
- Requires agreement with a participating custody partner
3. Credit Line API Keys
- For institutional users with a credit line agreement
- Access to credit line-specific endpoints only
- Requires signed credit line agreement with Binance.US
Installation
# Clone the repository
git clone https://github.com/nirholas/universal-crypto-mcp.git
cd universal-crypto-mcp/binance-us-mcp-server
# Install dependencies
npm install
# Build the project
npm run build
Configuration
Environment Variables
Create a .env file or set these environment variables:
BINANCE_US_API_KEY=your_api_key_here
BINANCE_US_API_SECRET=your_api_secret_here
Claude Desktop Configuration
Add to your Claude Desktop config file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"binance-us-mcp": {
"command": "node",
"args": ["/path/to/binance-us-mcp-server/build/index.js"],
"env": {
"BINANCE_US_API_KEY": "your_api_key",
"BINANCE_US_API_SECRET": "your_api_secret"
}
}
}
}
Usage
Development
# Run in development mode with hot reload
npm run dev
# Test with MCP Inspector
npm test
Production
# Build the project
npm run build
# Start the server
npm start
Available Tool Categories
Market Data (Public)
- Get ticker prices
- Get order book depth
- Get recent trades
- Get kline/candlestick data
- Get 24hr statistics
- Get exchange info
Spot Trading (Requires API Key)
- Place new orders (limit, market, stop-limit)
- Cancel orders
- Get open orders
- Get order status
- Get trade history
Wallet (Requires API Key)
- Get balances
- Get deposit address
- Get deposit history
- Get withdrawal history
- Withdraw funds
Account (Requires API Key)
- Get account information
- Get trade history
- Get API key permissions
Staking
- Get staking products
- Subscribe to staking
- Redeem staking
- Get staking history
OTC Trading
- Get OTC quotes
- Execute OTC trades
Sub-Account
- Create sub-account
- Get sub-account list
- Transfer between accounts
Custodial Solution (Special API Key)
- Custody-specific operations
- Partner integrations
Credit Line (Special API Key)
- Credit line management
- Institutional features
Security Best Practices
- Never share your API keys - Treat them like passwords
- Use IP restrictions - Whitelist only trusted IPs in your API settings
- Limit permissions - Only enable the permissions you need
- Use separate keys - Create different keys for different applications
- Rotate keys regularly - Generate new keys periodically
- Monitor activity - Check your account for unauthorized access
Rate Limits
Binance.US has the following rate limits:
- Request Weight: 1200 per minute
- Orders: 10 per second, 100,000 per day
- Raw Requests: 5000 per 5 minutes
The server handles rate limiting automatically, but be mindful of these limits when making many requests.
Error Handling
The server returns standardized error responses:
{
"success": false,
"error": {
"code": -1121,
"msg": "Invalid symbol."
}
}
Common error codes:
-1000: Unknown error-1002: Unauthorized-1021: Timestamp outside recvWindow-1022: Invalid signature-2010: New order rejected-2011: Cancel rejected
Contributing
Contributions are welcome! Please read the contributing guidelines before submitting pull requests.
Documentation
Detailed documentation is available in the docs/ folder:
- TOOLS.md - Complete tools reference with parameters, examples, and responses
- API_CLIENT.md - API client architecture, types, and error handling
- QUICK_REFERENCE.md - Fast lookup guide for all tools
- TRADING.md - Trading tools and order management (all 13 tools)
- TRADING_QUICK_REF.md - Trading tools cheat sheet
- ERROR_CODES.md - Complete error code reference with solutions
License
MIT License - see LICENSE for details.
Resources
Documentation
- Tools Reference - Complete documentation for all 93 tools
- Quick Reference - Concise tool lookup card
- Prompt Examples - Example prompts for Claude
- Changelog - Version history and changes