qe-connector 1.0.0__tar.gz

qe-connector-1.0.0/PKG-INFO

@@ -0,0 +1,561 @@
+Metadata-Version: 2.1
+Name: qe-connector
+Version: 1.0.0
+Summary: This is a lightweight library that works as a connector to Quantum Execute public API.
+Home-page: https://github.com/Quantum-Execute/qe-connector-python
+Author: Quantum-Execute
+License: MIT
+Keywords: Quantum-Execute,Public API
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.31.0
+Requires-Dist: websocket-client>=1.6.3
+Requires-Dist: pycryptodome>=3.15.0
+
+# Quantum Execute Python SDK
+
+[![Python Version](https://img.shields.io/pypi/pyversions/qe-connector)](https://pypi.org/project/qe-connector/)
+[![PyPI Version](https://img.shields.io/pypi/v/qe-connector)](https://pypi.org/project/qe-connector/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+这是 Quantum Execute 公共 API 的官方 Python SDK，为开发者提供了一个轻量级、易于使用的接口来访问 Quantum Execute 的交易服务。
+
+## 功能特性
+
+- ✅ 完整的 Quantum Execute API 支持
+- ✅ 交易所 API 密钥管理
+- ✅ 主订单创建与管理（TWAP、VWAP 等算法）
+- ✅ 订单查询和成交明细
+- ✅ 多种认证方式支持（HMAC、RSA、Ed25519）
+- ✅ 支持生产环境和测试环境
+- ✅ 异步和同步调用支持
+- ✅ 完善的错误处理和日志记录
+
+## 安装
+
+```bash
+pip install qe-connector
+```
+
+或者从源码安装：
+
+```bash
+git clone https://github.com/Quantum-Execute/qe-connector-python.git
+cd qe-connector-python
+pip install -e .
+```
+
+## 快速开始
+
+### 初始化客户端
+
+```python
+from qe.user import User as Client
+import logging
+
+# 配置日志（可选）
+logging.basicConfig(level=logging.INFO)
+
+# 创建生产环境客户端
+client = Client(
+    api_key="your-api-key",
+    api_secret="your-api-secret"
+)
+
+# 创建测试环境客户端
+client = Client(
+    api_key="your-api-key",
+    api_secret="your-api-secret",
+    base_url="https://testapi.quantumexecute.com"
+)
+```
+
+### 管理交易所 API
+
+#### 列出交易所 API 密钥
+
+```python
+# 获取所有交易所 API 密钥
+apis = client.list_exchange_apis()
+print(f"共有 {apis['total']} 个 API 密钥")
+
+for api in apis['items']:
+    print(f"账户: {api['accountName']}, 交易所: {api['exchange']}, 状态: {api['status']}")
+
+# 带分页和过滤
+apis = client.list_exchange_apis(
+    page=1,
+    pageSize=10,
+    exchange="binance"
+)
+```
+
+#### 添加交易所 API 密钥
+
+```python
+result = client.add_exchange_api(
+    accountName="我的币安账户",
+    exchange="binance",
+    apiKey="your-exchange-api-key",
+    apiSecret="your-exchange-api-secret",
+    enableTrading=True  # 启用交易权限
+)
+
+if result['success']:
+    print(f"API Key 添加成功，ID: {result['id']}")
+```
+
+### 创建主订单
+
+#### TWAP 订单示例
+
+```python
+# 创建一个 TWAP 订单，在 30 分钟内分批买入价值 $10,000 的 BTC
+response = client.create_master_order(
+    algorithm="TWAP",
+    algorithmType="TIME_WEIGHTED",
+    exchange="binance",
+    symbol="BTCUSDT",
+    marketType="SPOT",
+    side="BUY",
+    apiKeyId="your-api-key-id",  # 从 list_exchange_apis 获取
+    orderNotional=10000,          # $10,000 名义价值
+    startTime="2024-01-01T10:00:00Z",
+    endTime="2024-01-01T10:30:00Z",
+    executionDuration="60",       # 每 60 秒执行一次
+    mustComplete=True,            # 必须完成全部订单
+    worstPrice=-1,               # -1 表示无最差价格限制
+    clientId="my-order-001"      # 自定义订单 ID
+)
+
+if response.get('success'):
+    print(f"主订单创建成功，ID: {response['masterOrderId']}")
+```
+
+#### VWAP 订单示例
+
+```python
+# 创建 VWAP 订单，根据市场成交量分布执行
+response = client.create_master_order(
+    algorithm="VWAP",
+    algorithmType="VOLUME_WEIGHTED",
+    exchange="binance",
+    symbol="ETHUSDT",
+    marketType="SPOT",
+    side="SELL",
+    apiKeyId="your-api-key-id",
+    totalQuantity=5.0,            # 卖出 5 ETH
+    strategyType="AGGRESSIVE",     # 激进策略
+    startTime="2024-01-01T09:00:00Z",
+    endTime="2024-01-01T17:00:00Z",
+    makerRateLimit=0.3,           # 最多 30% Maker 订单
+    povLimit=0.1,                 # 最多占市场成交量的 10%
+    notes="VWAP 卖出 ETH"         # 订单备注
+)
+```
+
+#### 期货订单示例
+
+```python
+# 创建期货 TWAP 订单
+response = client.create_master_order(
+    algorithm="TWAP",
+    algorithmType="TIME_WEIGHTED",
+    exchange="binance",
+    symbol="BTCUSDT",
+    marketType="FUTURES",
+    side="BUY",
+    apiKeyId="your-api-key-id",
+    totalQuantity=0.1,            # 0.1 BTC
+    executionDuration="1800",     # 30 分钟
+    marginType="CROSS",           # 全仓模式（或 "ISOLATED" 逐仓）
+    reduceOnly=False,             # 非只减仓
+    worstPrice=55000.0,          # 最差价格限制
+    upTolerance="0.001",         # 向上容差 0.1%
+    lowTolerance="0.001",        # 向下容差 0.1%
+    strictUpBound=True           # 严格上限
+)
+```
+
+### 查询订单
+
+#### 查询主订单列表
+
+```python
+# 查询所有主订单
+orders = client.get_master_orders()
+
+# 带过滤条件查询
+orders = client.get_master_orders(
+    page=1,
+    pageSize=20,
+    status="ACTIVE",              # 活跃订单
+    symbol="BTCUSDT",
+    startTime="2024-01-01T00:00:00Z",
+    endTime="2024-01-31T23:59:59Z"
+)
+
+# 打印订单信息
+for order in orders['items']:
+    print(f"""
+    订单 ID: {order['masterOrderId']}
+    算法: {order['algorithm']}
+    交易对: {order['symbol']}
+    方向: {order['side']}
+    状态: {order['status']}
+    完成度: {order['completionProgress'] * 100:.2f}%
+    平均价格: {order['averagePrice']}
+    已成交数量: {order['filledQuantity']} / {order['totalQuantity']}
+    """)
+```
+
+#### 查询成交明细
+
+```python
+# 查询特定主订单的成交明细
+fills = client.get_order_fills(
+    masterOrderId="your-master-order-id",
+    page=1,
+    pageSize=50
+)
+
+# 查询所有成交
+fills = client.get_order_fills(
+    symbol="BTCUSDT",
+    startTime="2024-01-01T00:00:00Z",
+    endTime="2024-01-01T23:59:59Z"
+)
+
+# 计算总成交额和手续费
+total_value = 0
+total_fee = 0
+
+for fill in fills['items']:
+    print(f"""
+    成交时间: {fill['orderCreatedTime']}
+    交易对: {fill['symbol']}
+    方向: {fill['side']}
+    成交价格: {fill['price']}
+    成交数量: {fill['filledQuantity']}
+    成交金额: {fill['filledValue']}
+    手续费: {fill['fee']}
+    """)
+    total_value += fill['filledValue']
+    total_fee += fill['fee']
+
+print(f"总成交额: ${total_value:.2f}, 总手续费: ${total_fee:.2f}")
+```
+
+### 取消订单
+
+```python
+response = client.cancel_master_order(
+    masterOrderId="your-master-order-id",
+    reason="用户手动取消"  # 可选的取消原因
+)
+
+if response.get('success'):
+    print("订单取消成功")
+else:
+    print(f"订单取消失败: {response.get('message')}")
+```
+
+## 错误处理
+
+SDK 提供了详细的错误类型，方便进行精确的错误处理：
+
+```python
+from qe.error import ClientError, APIError
+
+try:
+    response = client.create_master_order(
+        # ... 订单参数
+    )
+except APIError as error:
+    # API 返回的业务错误
+    print(f"API 错误 - 代码: {error.code}, 原因: {error.reason}, 消息: {error.message}")
+    print(f"追踪 ID: {error.trace_id}")  # 用于技术支持
+except ClientError as error:
+    # 客户端错误（如参数错误、网络错误等）
+    print(f"客户端错误 - 状态码: {error.status_code}, 错误消息: {error.error_message}")
+except Exception as error:
+    # 其他未预期的错误
+    print(f"未知错误: {error}")
+```
+
+## 高级配置
+
+### 配置超时和代理
+
+```python
+client = Client(
+    api_key="your-api-key",
+    api_secret="your-api-secret",
+    timeout=30,  # 30 秒超时
+    proxies={
+        'https': 'http://proxy.example.com:8080'
+    }
+)
+```
+
+### 使用 RSA 或 Ed25519 签名
+
+```python
+# 使用 RSA 私钥
+with open('private_key.pem', 'r') as f:
+    private_key = f.read()
+
+client = Client(
+    api_key="your-api-key",
+    private_key=private_key,
+    private_key_pass="your-password"  # 如果私钥有密码
+)
+
+# 使用 Ed25519 私钥
+with open('ed25519_key.pem', 'r') as f:
+    ed25519_key = f.read()
+
+client = Client(
+    api_key="your-api-key",
+    private_key=ed25519_key
+)
+```
+
+### 显示请求限制使用情况
+
+```python
+client = Client(
+    api_key="your-api-key",
+    api_secret="your-api-secret",
+    show_limit_usage=True,
+    show_header=True
+)
+
+# API 响应将包含限制信息
+response = client.get_master_orders()
+if isinstance(response, dict) and 'limit_usage' in response:
+    print(f"限制使用情况: {response['limit_usage']}")
+    print(f"实际数据: {response['data']}")
+```
+
+### 配置日志
+
+```python
+import logging
+from qe.lib.utils import config_logging
+
+# 配置详细日志
+config_logging(logging, logging.DEBUG)
+
+# 只记录警告和错误
+config_logging(logging, logging.WARNING)
+```
+
+## 完整示例
+
+### 完整的交易流程示例
+
+```python
+import logging
+from qe.user import User as Client
+from qe.error import ClientError, APIError
+from qe.lib.utils import config_logging
+import time
+
+# 配置日志
+config_logging(logging, logging.INFO)
+logger = logging.getLogger(__name__)
+
+# 初始化客户端
+client = Client("your-api-key", "your-api-secret")
+
+try:
+    # 1. 获取可用的 API 密钥
+    apis = client.list_exchange_apis(exchange="binance")
+    if not apis['items']:
+        logger.error("没有找到可用的币安 API 密钥")
+        exit(1)
+    
+    api_key_id = apis['items'][0]['id']
+    logger.info(f"使用 API 密钥: {api_key_id}")
+    
+    # 2. 创建 TWAP 订单
+    order_response = client.create_master_order(
+        algorithm="TWAP",
+        algorithmType="TIME_WEIGHTED",
+        exchange="binance",
+        symbol="BTCUSDT",
+        marketType="SPOT",
+        side="BUY",
+        apiKeyId=api_key_id,
+        orderNotional=1000,  # $1000
+        startTime="2024-01-01T10:00:00Z",
+        endTime="2024-01-01T10:10:00Z",
+        executionDuration="30",  # 每 30 秒执行一次
+        mustComplete=True,
+        clientId=f"test_order_{int(time.time())}"
+    )
+    
+    if not order_response.get('success'):
+        logger.error(f"创建订单失败: {order_response.get('message')}")
+        exit(1)
+    
+    master_order_id = order_response['masterOrderId']
+    logger.info(f"订单创建成功，ID: {master_order_id}")
+    
+    # 3. 监控订单状态
+    while True:
+        orders = client.get_master_orders(
+            page=1,
+            pageSize=1,
+            status="ACTIVE"
+        )
+        
+        if not orders['items']:
+            logger.info("订单已完成或取消")
+            break
+        
+        order = orders['items'][0]
+        logger.info(f"订单进度: {order['completionProgress'] * 100:.2f}%, "
+                   f"已成交: {order['filledQuantity']}/{order['totalQuantity']}")
+        
+        # 检查是否需要取消
+        if order['completionProgress'] > 0.5:  # 完成超过 50%
+            logger.info("演示：取消订单")
+            cancel_response = client.cancel_master_order(
+                masterOrderId=master_order_id,
+                reason="演示取消"
+            )
+            if cancel_response.get('success'):
+                logger.info("订单已取消")
+            break
+        
+        time.sleep(10)  # 每 10 秒检查一次
+    
+    # 4. 获取最终成交明细
+    fills = client.get_order_fills(masterOrderId=master_order_id)
+    logger.info(f"总成交笔数: {fills['total']}")
+    
+    for fill in fills['items']:
+        logger.info(f"成交: {fill['side']} {fill['filledQuantity']} {fill['symbol']} "
+                   f"@ {fill['price']}, 手续费: {fill['fee']}")
+
+except APIError as error:
+    logger.error(f"API 错误: {error}")
+except ClientError as error:
+    logger.error(f"客户端错误: {error}")
+except Exception as error:
+    logger.error(f"未知错误: {error}")
+```
+
+## API 文档
+
+完整的 API 文档请参考 [Quantum Execute API 文档](https://docs.quantumexecute.com)
+
+## 支持的算法类型
+
+- **TWAP (Time Weighted Average Price)**: 时间加权平均价格算法
+- **VWAP (Volume Weighted Average Price)**: 成交量加权平均价格算法
+- **POV (Percentage of Volume)**: 成交量百分比算法
+- **IMPLEMENTATION_SHORTFALL**: 执行缺口算法
+- 更多算法类型请参考 API 文档
+
+## 示例代码
+
+更多示例代码请参考 [examples](./examples) 目录：
+
+- [添加交易所 API](examples/user/add_exchange_api.py)
+- [创建主订单](examples/user/create_master_order.py)
+- [取消主订单](examples/user/cancel_master_order.py)
+- [查询订单列表](examples/user/get_master_orders.py)
+- [查询成交明细](examples/user/get_order_fills.py)
+
+## 开发和测试
+
+### 安装开发依赖
+
+```bash
+pip install -r requirements/requirements-dev.txt
+```
+
+### 运行测试
+
+```bash
+python -m pytest tests/
+```
+
+### 代码格式化
+
+```bash
+black qe/
+flake8 qe/
+```
+
+## 常见问题
+
+### 1. 如何获取 API 密钥？
+
+请登录 Quantum Execute 平台，在用户设置中创建 API 密钥。确保保管好您的密钥，不要将其提交到版本控制系统中。
+
+### 2. 时间戳错误怎么处理？
+
+如果遇到时间戳相关的错误，可能是您的系统时间与服务器时间不同步。请确保系统时间准确。
+
+### 3. 如何处理大量数据的分页？
+
+```python
+def get_all_orders(client):
+    all_orders = []
+    page = 1
+    page_size = 100
+    
+    while True:
+        result = client.get_master_orders(page=page, pageSize=page_size)
+        all_orders.extend(result['items'])
+        
+        if len(result['items']) < page_size:
+            break
+        page += 1
+    
+    return all_orders
+```
+
+### 4. 如何设置订单的时间？
+
+时间格式使用 ISO 8601 标准，例如：
+- UTC 时间：`2024-01-01T10:00:00Z`
+- 带时区：`2024-01-01T18:00:00+08:00`
+
+## 贡献指南
+
+欢迎提交 Issue 和 Pull Request！请确保：
+
+1. 代码符合 PEP 8 规范
+2. 添加适当的测试
+3. 更新相关文档
+
+## 更新日志
+
+### v1.0.0 (2024-01-01)
+- 初始版本发布
+- 支持完整的 Quantum Execute API
+- 支持多种认证方式
+- 完善的错误处理
+
+## 许可证
+
+本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件。
+
+## 联系我们
+
+- 官网：[https://quantumexecute.com](https://quantumexecute.com)
+- 邮箱：support@quantumexecute.com
+- GitHub：[https://github.com/Quantum-Execute/qe-connector-python](https://github.com/Quantum-Execute/qe-connector-python)
+