@nirholas/bnbchain-mcp 1.0.0

package/binance-us-mcp-server/docs/CUSTODIAL_SOLUTION.md

@@ -0,0 +1,334 @@
+# Binance.US Custodial Solution Guide
+
+This guide provides detailed information about using the Binance.US Custodial Solution API through the MCP Server.
+
+## Overview
+
+The Custodial Solution API is designed for **institutional custody partners** who have signed a Custody Exchange Network (CEN) agreement with Binance.US. This allows qualified custodians like Anchorage Digital and BitGo to provide their clients with direct access to Binance.US liquidity.
+
+## Prerequisites
+
+1. **Custody Partner Agreement**: Your organization must have a signed agreement with a participating custody partner
+2. **Custodial Solution API Keys**: Generated through your custody partner (not through standard Binance.US API management)
+3. **Rail Selection**: Know which custody rail you're using (`anchorage` or `bitgo`)
+
+> ⚠️ **Important**: Standard Binance.US exchange API keys will NOT work with custodial endpoints.
+
+## Architecture
+
+```
+┌──────────────────┐     ┌─────────────────┐     ┌─────────────────┐
+│  Your Trading    │────▶│  Custody        │────▶│  Binance.US     │
+│  Application     │     │  Partner        │     │  Exchange       │
+│                  │     │  (Anchorage/    │     │                 │
+│                  │◀────│   BitGo)        │◀────│                 │
+└──────────────────┘     └─────────────────┘     └─────────────────┘
+         │                                                │
+         └───────────────────────────────────────────────┘
+                    Custodial Solution API
+```
+
+## Available Tools
+
+### Balance & Account
+
+| Tool | Description |
+|------|-------------|
+| `binance_us_custodian_balance` | Get custodial account balance |
+| `binance_us_custodian_account_info` | Get account information |
+
+### Transfers
+
+| Tool | Description |
+|------|-------------|
+| `binance_us_custodian_transfer_custody_to_exchange` | Move funds from custody to exchange |
+| `binance_us_custodian_transfer_exchange_to_custody` | Move funds from exchange to custody |
+| `binance_us_custodian_transfer_status` | Check transfer status |
+| `binance_us_custodian_transfer_history` | Get transfer history |
+
+### Trading
+
+| Tool | Description |
+|------|-------------|
+| `binance_us_custodian_place_order` | Place a spot order |
+| `binance_us_custodian_cancel_order` | Cancel an order |
+| `binance_us_custodian_get_order` | Get order status |
+| `binance_us_custodian_open_orders` | List open orders |
+| `binance_us_custodian_all_orders` | Get all orders history |
+| `binance_us_custodian_trades` | Get trade history |
+
+### OCO Orders
+
+| Tool | Description |
+|------|-------------|
+| `binance_us_custodian_oco_order` | Place OCO order |
+| `binance_us_custodian_cancel_oco` | Cancel OCO order |
+| `binance_us_custodian_get_oco` | Get OCO order status |
+| `binance_us_custodian_all_oco` | List all OCO orders |
+
+### Settlement
+
+| Tool | Description |
+|------|-------------|
+| `binance_us_custodian_settlement_request` | Request asset settlement |
+| `binance_us_custodian_settlement_status` | Check settlement status |
+| `binance_us_custodian_settlement_history` | Get settlement history |
+
+## Common Workflows
+
+### Workflow 1: Check Balance and Trade
+
+```
+1. Check your custodial balance
+   → binance_us_custodian_balance (rail: "anchorage")
+
+2. Transfer assets from custody to exchange if needed
+   → binance_us_custodian_transfer_custody_to_exchange
+   
+3. Wait for transfer completion
+   → binance_us_custodian_transfer_status
+
+4. Place a trade
+   → binance_us_custodian_place_order
+
+5. Check order status
+   → binance_us_custodian_get_order
+
+6. After trading, settle back to custody
+   → binance_us_custodian_settlement_request
+```
+
+### Workflow 2: Batch Order Management
+
+```
+1. Check open orders
+   → binance_us_custodian_open_orders (rail: "bitgo")
+
+2. Cancel specific orders if needed
+   → binance_us_custodian_cancel_order
+
+3. Place new orders
+   → binance_us_custodian_place_order
+
+4. Monitor trades
+   → binance_us_custodian_trades
+```
+
+### Workflow 3: End-of-Day Settlement
+
+```
+1. Get all completed trades
+   → binance_us_custodian_trades (with time range)
+
+2. Check exchange balances
+   → binance_us_custodian_balance
+
+3. Request settlement for each asset
+   → binance_us_custodian_settlement_request
+
+4. Verify settlement completion
+   → binance_us_custodian_settlement_status
+```
+
+## Rail Parameter
+
+Every custodial tool requires a `rail` parameter specifying your custody provider:
+
+| Rail Value | Provider | Description |
+|------------|----------|-------------|
+| `anchorage` | Anchorage Digital | US-based qualified custodian |
+| `bitgo` | BitGo | Multi-signature custody platform |
+
+Example:
+```json
+{
+  "asset": "BTC",
+  "rail": "anchorage"
+}
+```
+
+## Transfer Flow
+
+### Custody → Exchange Transfer
+
+```
+┌─────────────┐         ┌─────────────┐         ┌─────────────┐
+│   Custody   │         │   Transit   │         │  Exchange   │
+│   Wallet    │────────▶│   (Locked)  │────────▶│   Balance   │
+│             │         │             │         │             │
+│  BTC: 10.0  │         │  BTC: 1.0   │         │  BTC: 1.0   │
+│             │         │  (pending)  │         │  (ready)    │
+└─────────────┘         └─────────────┘         └─────────────┘
+```
+
+**Steps:**
+1. Call `binance_us_custodian_transfer_custody_to_exchange`
+2. Assets are locked in transit
+3. Once confirmed, assets appear in exchange balance
+4. Ready for trading
+
+### Exchange → Custody Settlement
+
+```
+┌─────────────┐         ┌─────────────┐         ┌─────────────┐
+│  Exchange   │         │ Settlement  │         │   Custody   │
+│   Balance   │────────▶│  (Process)  │────────▶│   Wallet    │
+│             │         │             │         │             │
+│  USD: 50K   │         │  USD: 50K   │         │  USD: +50K  │
+│             │         │  (pending)  │         │             │
+└─────────────┘         └─────────────┘         └─────────────┘
+```
+
+**Steps:**
+1. Call `binance_us_custodian_settlement_request`
+2. Assets enter settlement process
+3. Custody partner confirms receipt
+4. Assets appear in custody wallet
+
+## Order Types
+
+### Supported Order Types
+
+| Type | Description | Required Parameters |
+|------|-------------|-------------------|
+| `LIMIT` | Limit order at specified price | quantity, price, timeInForce |
+| `MARKET` | Market order at best price | quantity |
+| `STOP_LOSS` | Stop loss market order | quantity, stopPrice |
+| `STOP_LOSS_LIMIT` | Stop loss limit order | quantity, price, stopPrice, timeInForce |
+| `TAKE_PROFIT` | Take profit market order | quantity, stopPrice |
+| `TAKE_PROFIT_LIMIT` | Take profit limit order | quantity, price, stopPrice, timeInForce |
+
+### Time in Force
+
+| Value | Description |
+|-------|-------------|
+| `GTC` | Good Till Cancelled |
+| `IOC` | Immediate or Cancel |
+| `FOK` | Fill or Kill |
+
+## Example Requests
+
+### Check Balance
+
+```json
+Tool: binance_us_custodian_balance
+Parameters:
+{
+  "asset": "BTC",
+  "rail": "anchorage"
+}
+```
+
+Response:
+```json
+{
+  "asset": "BTC",
+  "free": "5.25000000",
+  "locked": "0.50000000",
+  "total": "5.75000000"
+}
+```
+
+### Place Limit Order
+
+```json
+Tool: binance_us_custodian_place_order
+Parameters:
+{
+  "symbol": "BTCUSD",
+  "side": "BUY",
+  "type": "LIMIT",
+  "quantity": "0.1",
+  "price": "45000",
+  "timeInForce": "GTC",
+  "rail": "anchorage"
+}
+```
+
+Response:
+```json
+{
+  "symbol": "BTCUSD",
+  "orderId": 123456789,
+  "clientOrderId": "abc123",
+  "transactTime": 1706000000000,
+  "price": "45000.00",
+  "origQty": "0.1",
+  "executedQty": "0.0",
+  "status": "NEW",
+  "type": "LIMIT",
+  "side": "BUY"
+}
+```
+
+### Request Settlement
+
+```json
+Tool: binance_us_custodian_settlement_request
+Parameters:
+{
+  "asset": "USD",
+  "amount": "50000",
+  "rail": "bitgo"
+}
+```
+
+Response:
+```json
+{
+  "settlementId": "settle_789xyz",
+  "asset": "USD",
+  "amount": "50000.00",
+  "status": "PENDING",
+  "requestTime": 1706000000000,
+  "estimatedCompletionTime": 1706003600000
+}
+```
+
+## Error Handling
+
+### Common Errors
+
+| Error Code | Message | Cause |
+|------------|---------|-------|
+| -1002 | Unauthorized | Invalid or missing API key |
+| -1015 | Too many requests | Rate limit exceeded |
+| -2010 | Order rejected | Insufficient balance or invalid parameters |
+| -3001 | Invalid rail | Rail parameter not recognized |
+| -3002 | Transfer failed | Transfer could not be completed |
+| -3003 | Settlement pending | Previous settlement still in progress |
+
+### Error Response Format
+
+```json
+{
+  "code": -2010,
+  "msg": "Order rejected: Insufficient balance"
+}
+```
+
+## Rate Limits
+
+Custodial endpoints have separate rate limits from standard exchange endpoints:
+
+| Limit Type | Value |
+|------------|-------|
+| Orders per second | 5 |
+| Orders per day | 50,000 |
+| Transfers per minute | 10 |
+| Settlements per hour | 20 |
+
+## Security Best Practices
+
+1. **Secure API Keys**: Store custodial API keys in secure vaults, never in code
+2. **IP Whitelisting**: Configure allowed IPs in your custody partner's settings
+3. **Audit Logging**: Log all custodial operations for compliance
+4. **Dual Control**: Implement approval workflows for large settlements
+5. **Regular Reconciliation**: Compare custody and exchange balances daily
+
+## Support
+
+For custodial-specific issues:
+- Contact your custody partner (Anchorage/BitGo) for API key issues
+- Contact Binance.US institutional support for settlement issues
+- Review [Binance.US API Documentation](https://docs.binance.us/) for endpoint details

package/binance-us-mcp-server/docs/ERROR_CODES.md

@@ -0,0 +1,240 @@
+# Binance.US API Error Codes Reference
+
+Complete reference of Binance.US API error codes with solutions and troubleshooting tips.
+
+## Error Response Format
+
+All API errors return a JSON response:
+
+```json
+{
+  "code": -1121,
+  "msg": "Invalid symbol."
+}
+```
+
+The MCP server enhances error messages with helpful hints based on the error code.
+
+## General Server Errors (-1000 to -1099)
+
+| Code | Message | Solution |
+|------|---------|----------|
+| -1000 | Unknown error | Retry the request. If persistent, check Binance.US status page. |
+| -1001 | Disconnected | Internal error. Retry with exponential backoff. |
+| -1002 | Unauthorized | API key doesn't have permission for this endpoint. Check API settings. |
+| -1003 | Too many requests | Rate limit exceeded. Wait and retry. |
+| -1006 | Unexpected response | Check Binance.US status. May be maintenance. |
+| -1007 | Timeout | Request timed out. Retry with smaller payload if applicable. |
+| -1010 | Error message received | Check the specific error message for details. |
+| -1013 | Invalid quantity | Check the symbol's LOT_SIZE filter. |
+| -1014 | Unknown order composition | Check order parameters against symbol filters. |
+| -1015 | Too many orders | Reduce order frequency. Max 10/second, 100k/day. |
+| -1016 | Service shutting down | Maintenance in progress. Wait and retry. |
+| -1020 | Unsupported operation | This operation is not supported on Binance.US. |
+| -1021 | Timestamp outside recvWindow | Sync your system clock. Increase recvWindow (max 60000). |
+| -1022 | Invalid signature | Check API secret. Ensure proper HMAC-SHA256 signing. |
+
+## Request Parameter Errors (-1100 to -1199)
+
+| Code | Message | Solution |
+|------|---------|----------|
+| -1100 | Illegal characters | Remove special characters from parameters. |
+| -1101 | Too many parameters | Reduce the number of parameters sent. |
+| -1102 | Mandatory parameter missing | Include all required parameters for the endpoint. |
+| -1103 | Unknown parameter | Remove unrecognized parameters. |
+| -1104 | Unread parameters | Check parameter format and types. |
+| -1105 | Empty parameter | Provide a value for the parameter. |
+| -1106 | Parameter not required | Remove the unnecessary parameter. |
+| -1111 | Precision too high | Reduce decimal places. Check symbol's tick/step size. |
+| -1112 | No depth in order book | Try again later when liquidity is available. |
+| -1114 | TimeInForce not required | Remove timeInForce for MARKET orders. |
+| -1115 | Invalid timeInForce | Use GTC, IOC, or FOK. |
+| -1116 | Invalid orderType | Use LIMIT, MARKET, STOP_LOSS, etc. |
+| -1117 | Invalid side | Use BUY or SELL. |
+| -1118 | Empty newClientOrderId | Provide a valid client order ID or remove the parameter. |
+| -1119 | Empty originalClientOrderId | Provide the original client order ID. |
+| -1120 | Invalid interval | Use valid kline intervals: 1m, 5m, 15m, 1h, etc. |
+| -1121 | Invalid symbol | Check symbol format (e.g., BTCUSDT). Must be uppercase. |
+| -1125 | Invalid listenKey | Get a new listen key for user data stream. |
+| -1127 | Listen key interval too long | Reduce the listen key lifetime. |
+| -1128 | Invalid combination of params | Check mutually exclusive parameters. |
+| -1130 | Invalid data sent | Check parameter types and values. |
+| -1131 | recvWindow must be < 60000 | Reduce recvWindow value. Maximum is 60000ms. |
+| -1136 | Invalid newOrderRespType | Use ACK, RESULT, or FULL. |
+
+## Order Errors (-2000 to -2099)
+
+| Code | Message | Solution |
+|------|---------|----------|
+| -2010 | New order rejected | Check balance, symbol filters, and order parameters. |
+| -2011 | Cancel rejected | Order may already be filled or doesn't exist. |
+| -2013 | Order does not exist | Verify the orderId or clientOrderId. |
+| -2014 | Invalid API key format | Check API key format. Should not have extra spaces. |
+| -2015 | Invalid API key or permissions | Enable required permissions (e.g., Spot Trading). |
+| -2016 | No trading window | Trading is paused. Wait for market to reopen. |
+| -2018 | Balance not sufficient | Add funds or reduce order size. |
+| -2019 | Margin not sufficient | For margin accounts (not available on Binance.US). |
+| -2020 | Unable to fill | Order cannot be filled at current market conditions. |
+| -2021 | Order would trigger immediately | Adjust stop price for stop orders. |
+| -2022 | ReduceOnly rejected | Remove reduceOnly flag (for futures, not US). |
+| -2024 | Position side not match | Check position mode settings. |
+| -2025 | Reduce only | Not applicable to Binance.US spot trading. |
+| -2026 | Margin account error | Margin not available on Binance.US. |
+
+## Filter Errors (-9000 to -9999)
+
+| Code | Message | Solution |
+|------|---------|----------|
+| -9000 | Filter failure: PRICE_FILTER | Price outside allowed range. Check minPrice/maxPrice. |
+| -9001 | Filter failure: PERCENT_PRICE | Price too far from mark price. |
+| -9002 | Filter failure: LOT_SIZE | Quantity invalid. Check minQty/maxQty/stepSize. |
+| -9003 | Filter failure: MIN_NOTIONAL | Order value too low. Increase quantity × price. |
+| -9004 | Filter failure: ICEBERG_PARTS | Check iceberg order parts limit. |
+| -9005 | Filter failure: MARKET_LOT_SIZE | Market order quantity invalid. |
+| -9006 | Filter failure: MAX_NUM_ORDERS | Too many open orders. Cancel some first. |
+| -9007 | Filter failure: MAX_NUM_ALGO_ORDERS | Too many algo orders. Cancel some first. |
+| -9008 | Filter failure: MAX_NUM_ICEBERG_ORDERS | Too many iceberg orders. |
+| -9009 | Filter failure: TRAILING_DELTA | Invalid trailing delta value. |
+| -9010 | Filter failure: EXCHANGE_MAX_NUM_ORDERS | Exchange-wide order limit reached. |
+| -9011 | Filter failure: EXCHANGE_MAX_NUM_ALGO_ORDERS | Exchange-wide algo order limit reached. |
+
+## OCO-Specific Errors
+
+| Code | Message | Solution |
+|------|---------|----------|
+| -2010 | OCO rejected | Check price relationships for OCO. SELL: limit > stop. BUY: limit < stop. |
+| -2011 | OCO cancel rejected | One or both orders may already be filled. |
+
+### OCO Price Rules
+
+**For SELL OCO:**
+```
+Limit Price > Last Market Price > Stop Price
+```
+- Limit order is above market (take profit)
+- Stop order is below market (stop loss)
+
+**For BUY OCO:**
+```
+Limit Price < Last Market Price < Stop Price
+```
+- Limit order is below market (buy the dip)
+- Stop order is above market (breakout buy)
+
+## Common Error Scenarios
+
+### Scenario 1: Order Rejected Due to Quantity
+```
+Error: -9002 LOT_SIZE
+```
+
+**Cause:** Quantity doesn't match symbol's lot size filter.
+
+**Solution:**
+1. Get exchange info for the symbol
+2. Find LOT_SIZE filter: `minQty`, `maxQty`, `stepSize`
+3. Adjust quantity: `minQty <= quantity <= maxQty`
+4. Round to stepSize: `quantity % stepSize == 0`
+
+### Scenario 2: Order Rejected Due to Price
+```
+Error: -9000 PRICE_FILTER
+```
+
+**Cause:** Price outside allowed range or wrong tick size.
+
+**Solution:**
+1. Get exchange info for the symbol
+2. Find PRICE_FILTER: `minPrice`, `maxPrice`, `tickSize`
+3. Adjust price: `minPrice <= price <= maxPrice`
+4. Round to tickSize
+
+### Scenario 3: Minimum Notional Not Met
+```
+Error: -9003 MIN_NOTIONAL
+```
+
+**Cause:** Order value (price × quantity) too small.
+
+**Solution:**
+1. Get exchange info for the symbol
+2. Find MIN_NOTIONAL filter: `minNotional`
+3. Ensure: `price × quantity >= minNotional`
+4. Typically $10 minimum on Binance.US
+
+### Scenario 4: Invalid Signature
+```
+Error: -1022 Signature for this request is not valid
+```
+
+**Causes:**
+- Wrong API secret
+- System clock not synchronized
+- Parameters changed after signing
+
+**Solutions:**
+1. Verify API secret is correct
+2. Sync system time with NTP server
+3. Don't modify parameters after signing
+4. Ensure proper URL encoding
+
+### Scenario 5: Timestamp Error
+```
+Error: -1021 Timestamp for this request is outside of the recvWindow
+```
+
+**Causes:**
+- System clock ahead/behind server time
+- Network latency
+
+**Solutions:**
+1. Sync system clock: `sudo ntpdate pool.ntp.org`
+2. Increase recvWindow (up to 60000ms)
+3. Use server time endpoint to check offset
+
+## Debugging Tips
+
+### 1. Use Test Orders First
+```
+binance_us_test_order
+```
+Tests order validity without placing it.
+
+### 2. Check Symbol Info
+Get exchange info to see all filters and requirements for a symbol.
+
+### 3. Verify API Permissions
+- Go to Binance.US API Management
+- Check which permissions are enabled
+- Ensure IP whitelist includes your server
+
+### 4. Check Timestamps
+```bash
+# Compare your time with server time
+curl https://api.binance.us/api/v3/time
+```
+
+### 5. Log Full Error Responses
+The MCP server includes the full error message with code and hint.
+
+## Rate Limit Errors
+
+When you hit rate limits:
+
+| HTTP Status | Meaning |
+|-------------|---------|
+| 429 | Rate limit exceeded |
+| 418 | IP banned (usually 5 min) |
+
+**Prevention:**
+- Implement request queuing
+- Use WebSocket for real-time data
+- Cache responses when appropriate
+- Respect weight limits per minute
+
+## Getting Help
+
+1. Check this error reference
+2. Review [Binance.US API Docs](https://docs.binance.us/)
+3. Test with smaller requests
+4. Check Binance.US status page for outages