# 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
```bash
# 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:
```bash
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):
```json
{
"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
```bash
# Run in development mode with hot reload
npm run dev
# Test with MCP Inspector
npm test
```
### Production
```bash
# 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
1. **Never share your API keys** - Treat them like passwords
2. **Use IP restrictions** - Whitelist only trusted IPs in your API settings
3. **Limit permissions** - Only enable the permissions you need
4. **Use separate keys** - Create different keys for different applications
5. **Rotate keys regularly** - Generate new keys periodically
6. **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:
```json
{
"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**](docs/TOOLS.md) - Complete tools reference with parameters, examples, and responses
- [**API_CLIENT.md**](docs/API_CLIENT.md) - API client architecture, types, and error handling
- [**QUICK_REFERENCE.md**](docs/QUICK_REFERENCE.md) - Fast lookup guide for all tools
- [**TRADING.md**](docs/TRADING.md) - Trading tools and order management (all 13 tools)
- [**TRADING_QUICK_REF.md**](docs/TRADING_QUICK_REF.md) - Trading tools cheat sheet
- [**ERROR_CODES.md**](docs/ERROR_CODES.md) - Complete error code reference with solutions
## License
MIT License - see [LICENSE](../LICENSE) for details.
## Resources
- [Binance.US API Documentation](https://docs.binance.us/)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [MCP SDK Documentation](https://github.com/modelcontextprotocol/sdk)
## Documentation
- [**Tools Reference**](docs/TOOLS_REFERENCE.md) - Complete documentation for all 93 tools
- [**Quick Reference**](docs/QUICK_REFERENCE.md) - Concise tool lookup card
- [**Prompt Examples**](docs/PROMPT_EXAMPLES.md) - Example prompts for Claude
- [**Changelog**](docs/CHANGELOG.md) - Version history and changes
