Binance.US MCP Server
# 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/Binance-US-MCP.git
cd Binance-US-MCP
# 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
All rights reserved. See [LICENSE](LICENSE).
## 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
---
## 🌐 Live HTTP Deployment
**Binance US MCP** is deployed and accessible over HTTP via [MCP Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) transport — no local installation required.
**Endpoint:**
```
https://modelcontextprotocol.name/mcp/binance-us-mcp
```
### Connect from any MCP Client
Add to your MCP client configuration (Claude Desktop, Cursor, SperaxOS, etc.):
```json
{
"mcpServers": {
"binance-us-mcp": {
"type": "http",
"url": "https://modelcontextprotocol.name/mcp/binance-us-mcp"
}
}
}
```
### Available Tools (3)
| Tool | Description |
|------|-------------|
| `get_ticker_price` | Get price on Binance.US |
| `get_24h_stats` | 24h statistics |
| `get_order_book` | Order book |
### Example Requests
**Get price on Binance.US:**
```bash
curl -X POST https://modelcontextprotocol.name/mcp/binance-us-mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_ticker_price","arguments":{"symbol":"BTCUSD"}}}'
```
**24h statistics:**
```bash
curl -X POST https://modelcontextprotocol.name/mcp/binance-us-mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_24h_stats","arguments":{"symbol":"ETHUSD"}}}'
```
**Order book:**
```bash
curl -X POST https://modelcontextprotocol.name/mcp/binance-us-mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_order_book","arguments":{"symbol":"BTCUSD","limit":5}}}'
```
### List All Tools
```bash
curl -X POST https://modelcontextprotocol.name/mcp/binance-us-mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```
### Also Available On
- **This repository**: [github.com/nirholas/Binance-US-MCP](https://github.com/nirholas/Binance-US-MCP). The SperaxOS marketplace listing is offline while its hosting is being migrated.
- **The full MCP catalog**: see [modelcontextprotocol.name](https://modelcontextprotocol.name)
> Powered by [modelcontextprotocol.name](https://modelcontextprotocol.name) — the open MCP HTTP gateway
## Star History
[](https://star-history.com/#nirholas/Binance-US-MCP&Date)
<!-- nirholas:watermark -->
---
<p align="center">
Built by <a href="https://github.com/nirholas"><b>nirholas</b></a> · <a href="https://x.com/nichxbt">@nichxbt</a> · <a href="https://github.com/nirholas">github.com/nirholas</a>
</p>
<!-- /nirholas:watermark -->
TDQS
Scored across 93 tools
Several tool pairs appear to be near-identical duplicates distinguished only by a 'cust_' vs 'custodial_' prefix (e.g., binance_us_cust_balance vs binance_us_custodial_balance, cust_wallet_transfer vs custodial_wallet_transfer, cust_settlement_history vs custodial_settlement_history). An agent would struggle to pick between these, and the custodial vs standard order tools (cancel_order vs cust_cancel_order) add further confusion.
Names generally follow snake_case with a binance_us_ prefix, which is readable. However the 'cust_' and 'custodial_' variants for what look like the same operations is a significant inconsistency that breaks any predictable pattern.
93 tools is far beyond a reasonable scope and is inflated by apparent duplicates. While Binance.US has many endpoints, this surface is heavy enough to overwhelm tool selection.
The surface is remarkably broad, covering market data, spot orders, OCO, OTC, OCBS, staking, sub-accounts, custodial solutions, credit line, and websocket management. Minor gaps exist but the domain is well covered.