# Unicorn WebSocket 集成说明

## 概述

已集成 `unicorn-binance-websocket-api`，提供高性能的实时WebSocket数据流支持。

## 功能特性

### 1. 高性能实时数据流
- 使用Unicorn库提供更高效的WebSocket连接
- 支持多路复用流（一个连接订阅多个交易对）
- 自动重连和错误恢复

### 2. 实时价格监控
- 订阅交易对的实时ticker数据
- 实时获取最新价格，无需轮询API
- 支持价格更新回调

### 3. K线数据流
- 订阅实时K线数据
- 支持多种时间周期（1m, 5m, 15m等）
- 实时更新K线数据

## 配置

在 `config.py` 中：

```python
TRADING_CONFIG = {
    # Unicorn WebSocket配置
    'USE_UNICORN_WEBSOCKET': True,  # 是否使用Unicorn WebSocket
}
```

## 使用方法

### 1. 自动启用

程序启动时会自动检测并启用Unicorn WebSocket（如果配置为True）。

### 2. 订阅实时价格

```python
# 在代码中订阅实时价格
symbols = ['BTCUSDT', 'ETHUSDT']
client.subscribe_realtime_prices(symbols, price_callback)

# 回调函数
async def price_callback(symbol, price, price_data):
    print(f"{symbol} 最新价格: {price}")
```

### 3. 获取实时价格

```python
# 获取实时价格（从WebSocket流）
price = client.get_realtime_price('BTCUSDT')
if price:
    print(f"BTCUSDT 实时价格: {price}")
```

### 4. 监控价格变化

```python
# 使用market_scanner监控价格
await scanner.monitor_price('BTCUSDT', price_callback)
```

## 优势

### 相比标准WebSocket

1. **性能更高**
   - 多路复用：一个连接订阅多个交易对
   - 更低的延迟
   - 更少的资源占用

2. **更稳定**
   - 自动重连机制
   - 错误恢复
   - 流管理更完善

3. **功能更丰富**
   - 支持多种数据流（ticker, kline等）
   - 流统计信息
   - 更好的数据解析

## 回退机制

如果Unicorn WebSocket启动失败或不可用，系统会自动回退到标准的`python-binance` WebSocket，确保功能正常。

## 注意事项

1. **依赖安装**
   ```bash
   pip install unicorn-binance-websocket-api==2.4.0
   ```

2. **测试网支持**
   - 自动检测测试网/生产网环境
   - 使用对应的WebSocket端点

3. **资源管理**
   - 程序退出时自动清理所有流
   - 避免资源泄漏

4. **性能考虑**
   - 订阅大量交易对时，注意系统资源
   - 建议订阅数量不超过100个

## 故障排查

### 问题1：Unicorn启动失败

**原因**：依赖未安装或版本不兼容
**解决**：
```bash
pip install unicorn-binance-websocket-api==2.4.0
```

### 问题2：无法获取实时价格

**原因**：未订阅该交易对
**解决**：先调用 `subscribe_realtime_prices()` 订阅

### 问题3：流数据丢失

**原因**：处理速度跟不上数据产生速度
**解决**：检查回调函数是否阻塞，优化处理逻辑

## 示例代码

```python
# 订阅多个交易对的实时价格
symbols = ['BTCUSDT', 'ETHUSDT', 'BNBUSDT']

async def on_price_update(symbol, price, price_data):
    print(f"{symbol}: {price}")
    # 可以在这里实现交易逻辑

# 订阅
client.subscribe_realtime_prices(symbols, on_price_update)

# 获取实时价格
btc_price = client.get_realtime_price('BTCUSDT')
print(f"BTC价格: {btc_price}")
```

## 技术细节

### 流管理

- 每个交易对对应一个stream_id
- 支持动态添加/删除订阅
- 自动管理流的生命周期

### 数据处理

- 异步处理流数据
- 支持多个回调函数
- 自动解析数据格式

### 性能优化

- 使用缓冲区减少API调用
- 批量处理数据
- 异步非阻塞处理

## 更新日志

- 2026-01-13：初始集成Unicorn WebSocket支持