@nirholas/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

# 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

• Binance.US API Documentation
• Model Context Protocol
• MCP SDK Documentation

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