# binance_client

**Repository Path**: chobit/binance_client

## Basic Information

- **Project Name**: binance_client
- **Description**: 币安SDK 客服端
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-26
- **Last Updated**: 2026-06-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 异步币安U本位合约客户端

基于币安官方SDK (`binance-sdk-derivatives-trading-usds-futures`) 实现的异步客户端，支持全异步架构、自动重连、频率限制、日志记录等功能。

## 功能特性

### 核心功能
- **账户资产查询**: 余额、账户信息、持仓信息
- **合约持仓与订单管理**: 下单、撤单、查询订单、杠杆设置、保证金模式切换
- **行情数据获取**: 价格、K线、深度、成交、资金费率、标记价格
- **WebSocket实时推送订阅**: K线、深度、成交、标记价格、所有行情
- **账户数据推送**: 账户更新、订单更新实时推送

### 技术特性
- **全异步架构**: 基于 `asyncio` 和 `aiohttp`
- **自动重连机制**: WebSocket连接自动重连
- **API请求频率限制**: 内置频率控制，避免触发API限制
- **自定义超时参数**: 可配置REST和WebSocket超时
- **完善日志记录**: 支持多级别日志配置
- **异常捕获与处理**: 完整的错误处理机制

## 安装

### 1. 安装依赖

```bash
pip install -r requirements.txt
```

### 2. 手动安装核心依赖

```bash
pip install binance-sdk-derivatives-trading-usds-futures aiohttp
```

## 快速开始

### 1. 基础使用

```python
import asyncio
from async_binance_usdt_futures_client import AsyncBinanceUsdtFuturesClient, ClientConfig, Environment

async def main():
    config = ClientConfig(
        api_key="your-api-key",
        api_secret="your-api-secret",
        environment=Environment.PRODUCTION
    )
    
    async with AsyncBinanceUsdtFuturesClient(config) as client:
        # 获取账户余额
        balances = await client.get_account_balance()
        for balance in balances:
            if float(balance['balance']) > 0:
                print(f"{balance['asset']}: {balance['balance']}")
        
        # 获取最新价格
        price = await client.get_price("BTCUSDT")
        print(f"BTCUSDT: {price['price']}")

asyncio.run(main())
```

### 2. WebSocket实时数据

```python
import asyncio
from async_binance_usdt_futures_client import AsyncBinanceUsdtFuturesClient, ClientConfig

async def main():
    config = ClientConfig(
        api_key="your-api-key",
        api_secret="your-api-secret"
    )
    
    async with AsyncBinanceUsdtFuturesClient(config) as client:
        # 回调函数
        def on_kline(data):
            print(f"K线更新: {data}")
        
        # 订阅K线数据
        stream = await client.subscribe_kline("BTCUSDT", "1m", on_kline)
        
        # 保持连接
        await asyncio.sleep(60)
        
        # 取消订阅
        await stream.unsubscribe()

asyncio.run(main())
```

### 3. 用户数据流

```python
import asyncio
from async_binance_usdt_futures_client import AsyncBinanceUsdtFuturesClient, ClientConfig

async def main():
    config = ClientConfig(
        api_key="your-api-key",
        api_secret="your-api-secret"
    )
    
    async with AsyncBinanceUsdtFuturesClient(config) as client:
        def on_user_data(data):
            print(f"用户数据: {data}")
        
        # 订阅用户数据流
        stream = await client.subscribe_user_data(
            callback=on_user_data,
            event_types=["ACCOUNT_UPDATE", "ORDER_TRADE_UPDATE"]
        )
        
        # 保持连接
        await asyncio.sleep(3600)

asyncio.run(main())
```

## 配置说明

### ClientConfig 参数

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `api_key` | str | 必填 | API密钥 |
| `api_secret` | str | 必填 | API密钥 |
| `environment` | Environment | PRODUCTION | 环境 (PRODUCTION/TESTNET) |
| `rest_timeout` | int | 5000 | REST超时时间(毫秒) |
| `ws_timeout` | int | 5000 | WebSocket超时时间(毫秒) |
| `max_retries` | int | 3 | 最大重试次数 |
| `retry_delay` | float | 1.0 | 重试延迟(秒) |
| `ws_reconnect_delay` | int | 5000 | WebSocket重连延迟(毫秒) |
| `proxy` | dict | None | 代理配置 |
| `log_level` | str | "INFO" | 日志级别 |
| `rate_limit_enabled` | bool | True | 启用频率限制 |
| `rate_limit_requests_per_minute` | int | 1200 | 每分钟请求数限制 |
| `rate_limit_orders_per_second` | int | 10 | 每秒订单数限制 |
| `rate_limit_orders_per_day` | int | 200000 | 每日订单数限制 |

### 环境配置

```python
# 生产环境
config = ClientConfig(
    api_key="your-api-key",
    api_secret="your-api-secret",
    environment=Environment.PRODUCTION
)

# 测试网
config = ClientConfig(
    api_key="your-testnet-api-key",
    api_secret="your-testnet-api-secret",
    environment=Environment.TESTNET
)
```

## 功能模块

### 1. 账户资产查询

```python
# 获取账户余额
balances = await client.get_account_balance()

# 获取账户信息
account = await client.get_account_info()

# 获取持仓信息
positions = await client.get_position_info()
positions = await client.get_position_info("BTCUSDT")  # 指定交易对
```

### 2. 合约持仓与订单管理

```python
# 设置杠杆
result = await client.set_leverage("BTCUSDT", 20)

# 切换保证金模式
result = await client.set_margin_type("BTCUSDT", "ISOLATED")

# 下限价单
order = await client.place_order(
    symbol="BTCUSDT",
    side="BUY",
    order_type="LIMIT",
    quantity="0.001",
    price="50000",
    time_in_force="GTC"
)

# 下市价单
order = await client.place_order(
    symbol="BTCUSDT",
    side="BUY",
    order_type="MARKET",
    quantity="0.001"
)

# 查询订单
order_info = await client.get_order("BTCUSDT", order_id)

# 获取当前挂单
open_orders = await client.get_open_orders("BTCUSDT")

# 获取所有订单
all_orders = await client.get_all_orders("BTCUSDT", limit=100)

# 撤销订单
result = await client.cancel_order("BTCUSDT", order_id)

# 撤销所有订单
result = await client.cancel_all_orders("BTCUSDT")
```

### 3. 行情数据获取

```python
# 获取最新价格
price = await client.get_price("BTCUSDT")

# 获取所有价格
prices = await client.get_prices()

# 获取K线数据
klines = await client.get_klines("BTCUSDT", "1h", limit=100)

# 获取订单簿深度
depth = await client.get_depth("BTCUSDT", limit=100)

# 获取近期成交
trades = await client.get_trades("BTCUSDT", limit=100)

# 获取资金费率
funding_rates = await client.get_funding_rate("BTCUSDT", limit=100)

# 获取标记价格
mark_price = await client.get_mark_price("BTCUSDT")

# 获取交易所信息
exchange_info = await client.get_exchange_info()
```

### 4. WebSocket实时推送订阅

```python
# 订阅K线数据
stream = await client.subscribe_kline("BTCUSDT", "1m", callback)

# 订阅深度数据
stream = await client.subscribe_depth("BTCUSDT", update_speed=100, callback=callback)

# 订阅成交数据
stream = await client.subscribe_trades("BTCUSDT", callback)

# 订阅标记价格
stream = await client.subscribe_mark_price("BTCUSDT", callback)

# 订阅所有行情
stream = await client.subscribe_all_tickers(callback)

# 取消订阅
await stream.unsubscribe()
```

### 5. 账户数据推送

```python
# 订阅用户数据流
stream = await client.subscribe_user_data(
    callback=callback,
    event_types=["ACCOUNT_UPDATE", "ORDER_TRADE_UPDATE"]
)
```

## 错误处理

```python
try:
    result = await client.place_order(...)
except Exception as e:
    print(f"错误: {e}")
```

## 示例文件

- `example_usage.py`: 详细的功能演示
- `async_binance_usdt_futures_client.py`: 客户端实现

## 运行示例

```bash
# 运行基础示例
python async_binance_usdt_futures_client.py basic

# 运行WebSocket示例
python async_binance_usdt_futures_client.py websocket

# 运行用户数据流示例
python async_binance_usdt_futures_client.py user_data

# 运行高级功能示例
python async_binance_usdt_futures_client.py advanced

# 运行完整演示
python example_usage.py
```

## 注意事项

1. **API密钥安全**: 请勿将API密钥提交到版本控制系统
2. **测试网**: 建议先在测试网测试，再使用生产环境
3. **频率限制**: 客户端已内置频率限制，但仍需注意API使用规范
4. **资金安全**: 交易操作涉及真实资金，请谨慎操作
5. **网络环境**: 确保网络连接稳定，特别是WebSocket连接

## 许可证

MIT License