cyqnt-trd 0.1.2__py3-none-any.whl → 0.1.7__py3-none-any.whl

cyqnt_trd/CHANGELOG_0.1.7.md

@@ -0,0 +1,111 @@
+# cyqnt_trd 0.1.7 新版本特性
+
+**cyqnt-trd** 0.1.7 是加密货币交易工具包当前版本，主要包含数据获取、交易信号与回测能力，并与 Binance SDK、链上数据接口集成。
+
+---
+
+## 一、数据获取 (get_data)
+
+### 1. 期货与现货 K 线
+
+- **`get_and_save_futures_klines`**：从 Binance 获取 USDT 永续期货 K 线并保存。
+- **`get_and_save_klines`** / **`get_and_save_klines_direct`**：现货 K 线获取与直接拉取。
+
+### 2. Web3 / 链上 K 线（0.1.7 增强）
+
+- **`get_and_save_web3_klines`**：通过 **dquery.sintral.io** 的 u-kline API 获取链上 K 线。
+  - 支持 BSC 等链、按 **USD 计价**、多周期（如 1min, 5min, 15min, 1h, 4h, 1d）。
+  - 支持时间范围、合约地址等参数。
+
+### 3. 带因子的 K 线接口（0.1.7 核心特性）
+
+在原始 K 线基础上，直接产出「K 线 + 归一化因子」结果，便于与排序/信号模型对接：
+
+| 接口 | 说明 |
+|------|------|
+| **`get_klines_with_factors`** | 输入原始 `klines_data`，输出整段带因子的 K 线列表（批量）。 |
+| **`get_klines_with_factors_at_time`** | 指定某一时间点，返回该时刻的**单条**带因子数据。 |
+| **`get_klines_with_factors_n_points`** | 以某时间为 end，向前取 **n 根** K 线的带因子数据。 |
+| **`get_kline_with_factor_at_time`** | 单因子版本的「某时刻单点」数据。 |
+| **`get_kline_with_factor_n_points`** | 单因子版本的「向前 n 点」数据。 |
+
+- 因子计算支持 **lookback 窗口**、**最小样本要求**、**因子缓存**，与 `model-training/trading_report_signal_ranking_v1` 中逻辑对齐。
+- 支持多种时间输入格式（datetime / 字符串 / 时间戳秒或毫秒）及 K 线周期（1m, 5m, 1h, 1d 等）。
+
+---
+
+## 二、交易信号 (trading_signal)
+
+### 1. 技术因子 (factor)
+
+统一约定：因子函数接收 `(data, index)`，输出数值；**正数看多、负数看空、0 中性**。
+
+- **均线类**：`ma_factor`, `ma_cross_factor`, `ema_factor`, `ema_cross_factor`
+- **动量/摆动**：`rsi_factor`, `momentum_factor`, `stochastic_k_factor`, `stochastic_tsi_fast_factor`, `williams_r_factor`, `uo_factor`, `cci_factor`
+- **趋势/强度**：`adx_factor`, `ao_factor`, `macd_level_factor`
+- **波动/通道**：`bbp_factor`
+
+### 2. 信号策略 (signal)
+
+- **`ma_signal`** / **`ma_cross_signal`**：均线及均线交叉信号。
+- **`factor_based_signal`**：基于单因子的买卖/持有信号。
+- **`multi_factor_signal`** / **`normalized_factor_signal`**：多因子组合与归一化因子信号。
+
+### 3. Alpha 因子库 (selected_alpha)
+
+- 提供 **alpha1 ~ alpha98** 等大量 Alpha 因子，便于选因子、组合与回测。
+- 配套 `alpha_utils`、`test_alpha`、`example_usage` 等示例与测试。
+
+---
+
+## 三、回测 (backtesting)
+
+- **`BacktestFramework`**：统一回测入口，可从本地数据路径加载 K 线并运行因子/策略测试。
+- **`FactorTester`**：单因子胜率与表现测试。
+- **`StrategyBacktester`**：完整策略回测（开平仓、收益统计等）。
+
+---
+
+## 四、其他模块
+
+- **online_trading**：`realtime_price_tracker` 等实时价格跟踪。
+- **utils**：如 `set_user` 等配置/工具。
+- **test_script**：网络信息、订单、实时价格等测试脚本。
+
+---
+
+## 五、依赖与版本
+
+- **Python**：>=3.8, <3.11  
+- **主要依赖**：pandas, numpy, matplotlib, scipy, requests  
+- **Binance 生态**：binance-sdk-spot, binance-sdk-derivatives-trading-usds-futures, binance-sdk-algo, binance-common  
+
+---
+
+## 六、使用示例（0.1.7）
+
+```python
+# 数据获取：期货 K 线
+from cyqnt_trd.get_data import get_and_save_futures_klines
+get_and_save_futures_klines("BTCUSDT", interval="1h", limit=100)
+
+# 带因子的 K 线（单点 / n 点）
+from cyqnt_trd.get_data import get_klines_with_factors_at_time, get_klines_with_factors_n_points
+# 按需传入 klines_data、时间、因子列表等
+
+# 链上 K 线
+from cyqnt_trd.get_data import get_and_save_web3_klines
+# 指定合约、链、周期等
+
+# 信号与回测
+from cyqnt_trd.trading_signal.factor import ma_factor, rsi_factor
+from cyqnt_trd.trading_signal.signal import ma_signal, factor_based_signal
+from cyqnt_trd.backtesting import BacktestFramework, FactorTester, StrategyBacktester
+
+framework = BacktestFramework(data_path="data/BTCUSDT_1h.json")
+result = framework.test_factor(ma_factor, short_window=5, long_window=20)
+```
+
+---
+
+*文档根据当前代码库整理，适用于 **cyqnt-trd 0.1.7**。*

cyqnt_trd/__init__.py

@@ -9,7 +9,7 @@ Cyqnt Trading Package
 - backtesting: 回测框架，支持因子测试和策略回测
 """
 
-__version__ = "0.1.0"
+__version__ = "0.1.7"
 
 # 导入主要模块
 from . import get_data

cyqnt_trd/backtesting/factor_test.py

@@ -103,8 +103,9 @@ class FactorTester:
             try:
                 # 计算因子值：传递数据切片而不是整个data和index
                 # 需要确定因子函数需要多少历史数据
-                # 为了兼容性，传递足够的数据切片（假设最多需要50个周期）
-                max_period = 50
+                # 为了兼容性，传递足够的数据切片
+                # 使用min_periods + 一些缓冲，或者至少50个周期
+                max_period = max(min_periods + 10, 50)
                 start_idx = max(0, i - max_period)
                 data_slice = self.data.iloc[start_idx:i+1].copy()
                 factor_value = factor_func(data_slice)

cyqnt_trd/get_data/__init__.py

@@ -1,15 +1,30 @@
 """
 数据获取模块
 
-提供从 Binance 获取期货和现货K线数据的功能
+提供从 Binance 获取期货和现货K线数据的功能，以及 Web3/链上 u-kline K 线数据，
+以及带因子的 K 线获取（公用 get_klines_with_factors、单点 at_time、向前 n 点）。
 """
 
 from .get_futures_data import get_and_save_futures_klines
 from .get_trending_data import get_and_save_klines, get_and_save_klines_direct
+from .get_web3_trending_data import get_and_save_web3_klines
+from .get_kline_with_factor import (
+    get_klines_with_factors,
+    get_klines_with_factors_at_time,
+    get_klines_with_factors_n_points,
+    get_kline_with_factor_at_time,
+    get_kline_with_factor_n_points,
+)
 
 __all__ = [
     'get_and_save_futures_klines',
     'get_and_save_klines',
     'get_and_save_klines_direct',
+    'get_and_save_web3_klines',
+    'get_klines_with_factors',
+    'get_klines_with_factors_at_time',
+    'get_klines_with_factors_n_points',
+    'get_kline_with_factor_at_time',
+    'get_kline_with_factor_n_points',
 ]
 

cyqnt_trd/get_data/get_futures_data.py

@@ -421,9 +421,9 @@ if __name__ == "__main__":
     for symbol in symbol_list:
         get_and_save_futures_klines(
             symbol=symbol,
-            interval="1d",
-            start_time="2024-01-01 00:00:00",
-            end_time="2025-11-30 23:59:59",
+            interval="30m",
+            start_time="2025-11-30 00:00:00",
+            end_time="2026-01-05 23:59:59",
             limit=1000,  # 每次请求的 limit，实际会分页获取所有数据
             output_dir=f"/Users/user/Desktop/repo/cyqnt_trd/tmp/data/{symbol}_futures"
         )