# binance_test

**Repository Path**: chifanxiaofendui/binance_test

## Basic Information

- **Project Name**: binance_test
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-05-27
- **Last Updated**: 2025-06-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README



# Binance Futures Python SDK

## 简介
这是一个用于币安合约交易的Python SDK，支持USDT本位永续合约(UM Futures)和币本位永续合约(CM Futures)。提供完整的REST API和WebSocket接口封装，包含市场数据查询、交易下单、账户管理、实时行情订阅等功能。

## 特性
- 完整支持币安合约交易API v1/v2
- 同步/异步双模式支持
- 全面覆盖市场数据、交易、账户管理接口
- 自动签名生成和参数验证
- 完善的错误处理机制
- 支持代理设置和日志配置
- 提供详细使用示例和文档

## 安装
### 从PyPI安装
```bash
pip install binance-futures
```

### 从源码安装
```bash
git clone https://github.com/binance/binance-futures.git
cd binance-futures
pip install -e .
```

## 快速开始
### 客户端初始化
#### 创建UM合约客户端
```python
from binance.um_futures import UMFutures

# 公共API访问
client = UMFutures()

# 带认证访问
client = UMFutures(key="API_KEY", secret="API_SECRET")
```

#### 创建CM合约客户端
```python
from binance.cm_futures import CMFutures

# 公共API访问
client = CMFutures()

# 带认证访问
client = CMFutures(key="API_KEY", secret="API_SECRET")
```

### 市场数据查询
#### 获取最新价格
```python
from binance.um_futures import UMFutures

client = UMFutures()
print(client.ticker_price("BTCUSDT"))
```

#### 获取深度数据
```python
depth_data = client.depth("BTCUSDT", **{"limit": 5})
print(depth_data)
```

#### 获取K线数据
```python
kline_data = client.klines("BTCUSDT", "1h", **{"limit": 5})
print(kline_data)
```

### 交易操作
#### 下单
```python
from binance.um_futures import UMFutures

client = UMFutures(key="API_KEY", secret="API_SECRET")
response = client.new_order(
    symbol="BTCUSDT",
    side="BUY",
    type="LIMIT",
    quantity=0.001,
    price=30000,
    timeInForce="GTC"
)
print(response)
```

#### 查询订单
```python
order_info = client.query_order(symbol="BTCUSDT", orderId=123456789)
print(order_info)
```

### WebSocket订阅
```python
from binance.websocket.um_futures.websocket_client import UMFuturesWebsocketClient

def message_handler(_, message):
    print(message)

ws_client = UMFuturesWebsocketClient()
ws_client.agg_trade(
    symbol="btcusdt",
    id=1,
    action=message_handler
)
```

## 目录结构
```
binance/
├── cm_futures/          # 币本位合约接口
├── um_futures/          # USDT本位合约接口
├── websocket/           # WebSocket接口封装
├── lib/                 # 工具函数模块
│   ├── authentication.py # 签名验证
│   └── utils.py          # 参数处理
├── api.py                # API基类
├── error.py              # 异常类定义
└── __version__.py        # 版本管理
```

## 错误处理
SDK定义了以下异常类型：
- `ClientError`: 客户端错误（参数校验、网络请求）
- `ServerError`: 服务器错误（5xx状态码）
- `ParameterRequiredError`: 必填参数缺失
- `ParameterValueError`: 参数值无效
- `ParameterTypeError`: 参数类型错误

示例：
```python
try:
    client.new_order(symbol="BTCUSDT", side="BUY", type="LIMIT")
except binance.ParameterRequiredError as e:
    print(f"缺少必要参数: {e}")
except binance.ClientError as e:
    print(f"客户端错误: {e.status_code} - {e.error_message}")
```

## 贡献指南
欢迎提交PR和Issue，请遵循以下规范：
1. 使用PEP8代码规范
2. 添加必要的单元测试
3. 保持接口与币安官方文档同步
4. 提交前请运行`tox`测试
5. 文档更新需同步中英文版本

## 许可证
MIT License，请查看[LICENSE.md](LICENSE.md)文件。

## 参考文档
- [币安合约官方文档](https://binance-docs.github.io)
- [API签名指南](https://binance-docs.github.io/apidocs/futures/cn/)

## 版本历史
查看[CHANGELOG.md](CHANGELOG.md)获取完整版本更新记录。