Metadata-Version: 2.4
Name: premium-futures-mcp
Version: 1.2.7
Summary: Premium Binance Futures MCP Server - Advanced trading tools for professional traders
Home-page: https://github.com/alexcandrabersiva/premium_futures_mcp
Author: Smart AI Trading
Author-email: Premium Trading Solutions <support@smartaitrading.org>
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://github.com/alexcandrabersiva/premium_futures_mcp
Project-URL: Documentation, https://github.com/alexcandrabersiva/premium_futures_mcp#readme
Project-URL: Repository, https://github.com/alexcandrabersiva/premium_futures_mcp
Project-URL: Issues, https://github.com/alexcandrabersiva/premium_futures_mcp/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp>=1.0.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: aiohttp>=3.8.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: aioredis>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: requires-python

# Premium Binance Futures MCP Server

**Advanced trading tools for professional traders with AI-powered market intelligence**

## 🎯 Status: Ready for Production

✅ **All systems operational and optimized**
- Fixed JSON serialization issues
- Optimized for minimal token usage (~50 tokens vs 60k+ previously)
- Robust error handling and caching
- Comprehensive tool suite with 50+ trading tools
- **NEW: Market Intelligence System with 24/7 monitoring**

📚 **New User?** Start with our [Complete Windows Setup Guide](docs/WINDOWS_SETUP_GUIDE.md) - no experience required!

📁 **Project Organization**: See our [Folder Organization Guide](docs/FOLDER_ORGANIZATION.md) for the clean project structure.

---

This is the premium version of the Binance Futures MCP Server, providing comprehensive order management, risk management, advanced trading capabilities, and **intelligent market analysis** for professional algorithmic trading and portfolio management.

## 🧠 NEW: Market Intelligence System

### Revolutionary Pre-Analyzed Market Data
**Problem Solved**: When AI assistants like GitHub Copilot analyze crypto markets, they typically make 400+ individual API calls for each token, causing massive delays and rate limiting.

**Our Solution**: 24/7 background monitoring with pre-calculated opportunity scores, delivering instant market analysis in seconds instead of minutes.

### 8-Factor Scoring System (0-60 points)
Our intelligent system analyzes every token using professional trading indicators:

1. **📈 Open Interest Changes (0-10 pts)** - Detects position accumulation patterns
2. **💸 Volume Spikes (0-8 pts)** - Identifies unusual trading activity  
3. **🧨 Funding Rate Extremes (0-6 pts)** - Spots squeeze opportunities
4. **🌀 Volatility Compression (0-5 pts)** - Finds breakout candidates
5. **🐋 Whale Activity (0-6 pts)** - Tracks institutional movements
6. **🗺️ Price Structure (0-4 pts)** - Analyzes key support/resistance levels
7. **🧠 Sentiment/Narrative (0-4 pts)** - Considers market themes (AI, L2, DeFi, etc.)
8. **📊 Volume/Market Cap Ratio (0-3 pts)** - Measures relative activity

### Market Intelligence Tools (9 new tools)
- **get_market_opportunities** - Get top-scored trading opportunities instantly
- **get_token_analysis** - Deep dive analysis for specific tokens
- **get_market_dashboard** - Comprehensive market overview
- **get_funding_extremes** - Find potential squeeze plays
- **get_volume_leaders** - Identify unusual volume activity
- **get_volatility_squeeze** - Discover breakout candidates
- **get_whale_activity** - Track institutional movements
- **get_narrative_plays** - Find tokens riding hot narratives
- **get_quick_scan** - Rapid high-conviction opportunities

### Example Usage
Instead of waiting minutes for analysis, users can now ask:
```
"Analyze the crypto market and find the best long opportunities"
```

And get instant results like:
```json
{
  "opportunities": [
    {
      "symbol": "SOLUSDT",
      "total_score": 52,
      "direction": "LONG", 
      "confidence": "HIGH",
      "recommendation": "STRONG LONG",
      "entry_timeframe": "IMMEDIATE",
      "score_breakdown": {
        "open_interest": 9,
        "volume_spike": 7,
        "funding_rate": 5,
        "volatility_squeeze": 4,
        "whale_activity": 6,
        "price_structure": 3,
        "sentiment": 4,
        "volume_mcap_ratio": 3
      }
    }
  ]
}
```

## 🚀 Premium Features

### Order Management Tools (8 tools)
- **place_order** - Place market, limit, and conditional orders
- **place_bracket_order** - Advanced bracket orders with take-profit and stop-loss
- **modify_order** - Modify existing orders
- **cancel_order** - Cancel individual orders
- **cancel_all_orders** - Cancel all open orders for a symbol
- **close_position** - Close positions with market orders
- **add_tp_sl_to_position** - Add take-profit and stop-loss to existing positions
- **get_order_status** - Get detailed order status information

### Risk Management Tools (4 tools)
- **set_leverage** - Adjust position leverage
- **change_margin_type** - Switch between cross and isolated margin
- **modify_isolated_position_margin** - Adjust margin for isolated positions
- **get_position_margin_history** - View margin adjustment history

### Position Management Tools (3 tools)
- **change_position_mode** - Switch between hedge and one-way position modes
- **get_position_risk** - Get detailed position risk metrics
- **get_adl_quantile** - Get auto-deleveraging quantile information

### Trading Configuration Tools (2 tools)
- **set_multi_asset_mode** - Configure multi-asset mode settings
- **get_multi_asset_mode** - Get current multi-asset mode status

### Trading History Tools (4 tools)
- **get_trade_history** - Get account trade history
- **get_order_history** - Get historical order data
- **get_income_history** - Get income/PnL history
- **get_commission_history** - Get commission payment history

### Enhanced Account Information (5 tools)
- **get_account_info** - Complete futures account information
- **get_balance** - Account balance details
- **get_position_info** - Current position information
- **get_position_mode** - Position mode settings
- **get_commission_rate** - Trading commission rates

### Advanced Market Data (12+ tools)
- **get_exchange_info** - Exchange trading rules and symbol information
- **get_ticker** - Real-time price tickers
- **get_order_book** - Market depth data
- **get_klines** - Historical price data
- **get_mark_price** - Mark price and funding rates
- **get_funding_rate_history** - Historical funding rates
- **get_top_gainers_losers** - Market movers analysis
- **get_market_overview** - Comprehensive market statistics
- And more advanced market data tools...

## 🔐 Authentication & Security

The premium server requires member key authentication in addition to your Binance API credentials:

```bash
export BINANCE_API_KEY="your_api_key"
export BINANCE_SECRET_KEY="your_secret_key"
export BINANCE_MCP_MEMBER_KEY="your_premium_member_key"
```

### Premium Member Key Validation

This package includes a premium member key validation system that authenticates premium users. The validation is handled automatically by the MCP server when you provide a valid member key. The system provides:

1. **Secure key validation** - Keys are validated against the premium database
2. **Automatic authentication** - No manual server configuration required
3. **Seamless integration** - Works directly with your MCP client configuration

## � Project Structure

This project is now cleanly organized for better development experience:

```
premium_futures_mcp/
├── 📂 src/                    # Source code
├── 📂 docs/                   # All documentation
├── 📂 tests/                  # All test files
├── 📂 scripts/                # Utility scripts
├── 📂 docker/                 # Docker configuration
├── 📂 examples/               # Configuration examples
└── 📄 README.md              # This file
```

**Key Benefits:**
- 🧹 **Clean root directory** - No more scattered test files
- 📚 **Organized documentation** - All docs in `docs/` folder
- 🧪 **Centralized testing** - All tests in `tests/` folder
- 🐳 **Docker isolation** - Docker files properly separated
- 🔗 **Easy access** - Symlinks for frequently used files

See [Folder Organization Guide](docs/FOLDER_ORGANIZATION.md) for complete details.

## �📦 Installation & Setup

> **✨ Simplified Setup**: Version 1.0.1+ includes streamlined configuration that doesn't require separate VPS server setup for basic usage. Premium key validation is handled automatically.

### From PyPI
```bash
pip install premium-futures-mcp==1.0.1
```

### From Source
```bash
git clone <premium-repo-url>
cd premium_futures_mcp
pip install -e .
```

### Configuration

Create an MCP configuration file (`mcp-config.json`):

#### Option 1: Direct Python Module (Recommended)
```json
{
  "github.copilot.chat.mcp.servers": {
    "premium-binance-futures": {
      "command": "python3",
      "args": [
        "-m", 
        "premium_futures_mcp.server"
      ],
      "env": {
        "BINANCE_API_KEY": "your_api_key",
        "BINANCE_SECRET_KEY": "your_secret_key", 
        "BINANCE_MCP_MEMBER_KEY": "your_premium_member_key"
      }
    }
  }
}
```

#### Option 2: Using Docker Container
```json
{
  "github.copilot.chat.mcp.servers": {
    "premium-binance-futures": {
      "command": "docker",
      "args": [
        "exec",
        "premium-mcp-server", 
        "python",
        "-m",
        "premium_futures_mcp.server"
      ]
    }
  }
}
```

#### Option 3: Using uvx (Alternative)
```json
{
  "github.copilot.chat.mcp.servers": {
    "premium-binance-futures": {
      "command": "uvx",
      "args": [
        "--from", 
        "premium-futures-mcp==1.0.1", 
        "premium-futures-mcp-server"
      ],
      "env": {
        "BINANCE_API_KEY": "your_api_key",
        "BINANCE_SECRET_KEY": "your_secret_key", 
        "BINANCE_MCP_MEMBER_KEY": "your_premium_member_key"
      }
    }
  }
}
```

### 🐳 Docker Setup

For containerized deployment, see our [Docker Setup Guide](DOCKER_SETUP_GUIDE.md).

**Quick Docker Start:**
```bash
# Copy environment template
cp .env.example .env
# Edit .env with your API keys

# Start with docker-compose
docker-compose -f docker-compose.mcp.yml up -d
```

> **Note**: Replace `your_api_key`, `your_secret_key`, and `your_premium_member_key` with your actual credentials. For security, consider using environment variables instead of hardcoding credentials.

## 🚨 Security Best Practices

1. **Never commit API keys** to version control
2. **Use environment variables** for all sensitive credentials
3. **Restrict API permissions** to futures trading only
4. **Enable IP restrictions** on your Binance API key
5. **Monitor account activity** regularly
6. **Use isolated margin** for risk management

## 🎯 Usage Examples

### Basic Order Placement
```python
# Place a market buy order
await client.call_tool("place_order", {
    "symbol": "BTCUSDT",
    "side": "BUY", 
    "type": "MARKET",
    "quantity": 0.001
})

# Place a limit sell order
await client.call_tool("place_order", {
    "symbol": "BTCUSDT",
    "side": "SELL",
    "type": "LIMIT", 
    "quantity": 0.001,
    "price": 45000
})
```

### Advanced Bracket Orders
```python
# Place bracket order with TP/SL
await client.call_tool("place_bracket_order", {
    "symbol": "BTCUSDT",
    "side": "BUY",
    "quantity": 0.001,
    "entry_type": "LIMIT",
    "entry_price": 42000,
    "take_profit_price": 45000,
    "stop_loss_price": 40000
})
```

### Risk Management
```python
# Set leverage for a symbol
await client.call_tool("set_leverage", {
    "symbol": "BTCUSDT",
    "leverage": 10
})

# Change margin type
await client.call_tool("change_margin_type", {
    "symbol": "BTCUSDT", 
    "margin_type": "ISOLATED"
})
```

## 📊 Monitoring & Analytics

The premium server includes advanced monitoring capabilities:
- Real-time position tracking
- PnL analysis and reporting
- Risk metrics calculation
- Performance analytics
- Commission tracking

## 🔧 Advanced Configuration

### Premium Key Server Setup

The premium key server is responsible for validating member keys. Here's how to set it up:

#### Docker Deployment (Recommended)

```bash
# Start the key server with Docker
cd premium_futures_mcp
docker-compose up -d

# Check the server status
docker ps | grep premium-key-server
```

#### Systemd Deployment (Alternative)

```bash
# Install the service file
sudo cp premium_key_server.service /etc/systemd/system/
sudo systemctl daemon-reload

# Start and enable the service
sudo systemctl start premium_key_server
sudo systemctl enable premium_key_server
```

#### Key Generation

Generate premium member keys for your customers:

```bash
# Simple key generation
./create_customer_key.sh customer123 customer@example.com

# Advanced key generation with options
./generate_key.sh --id customer456 --email customer@example.com --days 90 --usage 100
```

### Custom Risk Parameters
```json
{
  "risk_management": {
    "max_position_size": 1000,
    "max_leverage": 20,
    "stop_loss_threshold": 0.05
  }
}
```

### Performance Optimization
- Connection pooling for high-frequency trading
- Caching for market data
- Batch order processing
- WebSocket integration for real-time updates

## 📈 Professional Trading Features

### Algorithmic Trading Support
- Advanced order types (OCO, conditional orders)
- Portfolio management tools
- Multi-symbol strategies
- Automated risk management

### Institutional Features
- Sub-account management
- Advanced reporting
- Compliance tracking
- Audit trails

## 🆘 Support

For premium support and advanced features:
- Priority technical support
- Custom integration assistance
- Advanced strategy development
- Institutional-grade SLA

## ⚖️ License

Premium License - Commercial use requires valid subscription and member key authentication.

## ⚠️ Disclaimer

Trading futures involves substantial risk of loss. This software is provided for informational and educational purposes only. Always test strategies in a demo environment before live trading.

---

**Total Tools: 50+** | **Categories: 7** | **Professional Grade** ✨
