# 数据采集与处理流程

> 量化交易的核心是数据。本文档详细描述从原始数据采集到可用于策略执行的全流程，涵盖数据源、清洗方法、存储方案和实时流处理。

---

## 一、数据源分类

### 1.1 行情数据（Price Data）

**交易所 REST API**：

| 交易所 | API 文档 | 数据类型 | 限制 |
|--------|----------|----------|------|
| Binance | https://binance-docs.github.io/apidocs/ | K线、Tick、深度 | 1200 req/min |
| Bybit | https://bybit-docs.com/ | K线、Tick、深度 | 120 req/min |
| OKX | https://www.okx.com/docs-v5/ | K线、Tick、深度 | 60 req/10s |
| Coinbase | https://docs.cdp.coinbase.com/ | K线、Tick | 10 req/s |

**WebSocket 实时数据**：
```
Binance WebSocket 端点：wss://stream.binance.com:9443/ws/
订阅 K线：{"method": "SUBSCRIBE", "params": ["btcusdt@kline_1m"]}
订阅 Tick：{"method": "SUBSCRIBE", "params": ["btcusdt@aggTrade"]}
```

**tradehk 数据获取实现**（参考 `binanceApi.ts`）：
- 使用 Binance REST API 获取历史 K 线数据
- 使用 WebSocket 订阅实时 K 线更新
- 支持多时间周期：1m、3m、5m、10m、15m、30m、1h、4h、12h、1d、1w

---

### 1.2 链上数据（On-Chain Data）

**免费数据源**：

| 平台 | 数据类型 | 访问方式 |
|------|----------|----------|
| Glassnode | 链上指标、矿工数据 | API（免费层有限） |
| Nansen | 钱包标签、资金流向 | API（付费） |
| Dune Analytics | 自定义链上查询 | SQL 查询（免费） |
| The Graph | DeFi 协议数据 | GraphQL API |
| Etherscan | 以太坊交易数据 | API（免费） |

**关键链上指标**：

```
比特币链上指标：
- SOPR（已实现利润比率）：> 1 表示整体盈利，< 1 表示亏损
- MVRV（市值/已实现价值）：> 3.5 历史上对应牛市顶部
- 交易所净流入：正值表示资金流入交易所（抛压增加）
- 活跃地址数：反映网络使用率和用户活跃度
- 矿工持仓变化：矿工抛售压力指标
```

---

### 1.3 衍生品数据（Derivatives Data）

**资金费率（Funding Rate）**：
- 来源：各交易所永续合约页面或 API
- 含义：正值 = 多头付给空头，负值 = 空头付给多头
- 极端值（> 0.1% 或 < -0.1%）往往预示趋势反转

**未平仓合约（Open Interest）**：
- 未平仓合约增加 + 价格上涨 = 多头主导，趋势延续
- 未平仓合约减少 + 价格下跌 = 多头平仓，趋势可能反转

**清算数据**：
- 大规模清算往往是市场底部或顶部的信号
- 数据来源：Coinglass（https://www.coinglass.com/）

---

### 1.4 情绪数据（Sentiment Data）

**恐惧贪婪指数（Fear & Greed Index）**：
- 来源：Alternative.me API
- 范围：0（极度恐惧）- 100（极度贪婪）
- 极度恐惧（< 20）：历史上是买入机会
- 极度贪婪（> 80）：历史上是卖出时机

**社交媒体情绪**：
- Twitter/X 提及量和情绪分析
- Reddit 讨论热度（r/Bitcoin、r/CryptoCurrency）
- 工具：LunarCrush、Santiment

---

## 二、数据清洗流程

### 2.1 K 线数据清洗

```python
import pandas as pd
import numpy as np

def clean_kline_data(df: pd.DataFrame) -> pd.DataFrame:
    """
    K 线数据清洗流程
    """
    # 1. 删除重复数据
    df = df.drop_duplicates(subset=['timestamp'])
    
    # 2. 按时间排序
    df = df.sort_values('timestamp').reset_index(drop=True)
    
    # 3. 检测并处理缺失 K 线（用前值填充）
    expected_interval = df['timestamp'].diff().mode()[0]
    df = df.set_index('timestamp').asfreq(expected_interval, method='ffill')
    
    # 4. 过滤异常价格（价格为 0 或负值）
    df = df[(df['open'] > 0) & (df['high'] > 0) & 
            (df['low'] > 0) & (df['close'] > 0)]
    
    # 5. 修正 OHLC 逻辑错误（high < low 等）
    df['high'] = df[['open', 'high', 'low', 'close']].max(axis=1)
    df['low'] = df[['open', 'high', 'low', 'close']].min(axis=1)
    
    # 6. 处理成交量异常（成交量为负）
    df['volume'] = df['volume'].clip(lower=0)
    
    # 7. 过滤"刷量"数据（成交量极端异常）
    volume_mean = df['volume'].rolling(100).mean()
    volume_std = df['volume'].rolling(100).std()
    df = df[df['volume'] < volume_mean + 5 * volume_std]
    
    return df
```

### 2.2 常见数据问题

| 问题 | 原因 | 处理方法 |
|------|------|----------|
| 缺失 K 线 | 网络中断、交易所维护 | 前值填充或插值 |
| 价格跳空 | 正常市场现象 | 保留，但在回测中注意 |
| 成交量异常 | 刷量行为 | 统计方法过滤极端值 |
| 时区问题 | 不同交易所时区不同 | 统一转换为 UTC |
| 精度问题 | 浮点数精度 | 使用 Decimal 类型 |

---

## 三、数据存储方案

### 3.1 本地存储（适合小规模）

```
数据目录结构：
/data/
  ├── klines/
  │   ├── BTCUSDT/
  │   │   ├── 1m/2024-01.parquet
  │   │   ├── 1h/2024-01.parquet
  │   │   └── 1d/all.parquet
  │   └── ETHUSDT/
  │       └── ...
  ├── onchain/
  │   ├── glassnode/
  │   └── nansen/
  └── sentiment/
      └── fear_greed/
```

**推荐格式**：Parquet（列式存储，压缩率高，读取速度快）

```python
# 保存为 Parquet
df.to_parquet('BTCUSDT_1h_2024.parquet', compression='snappy')

# 读取 Parquet
df = pd.read_parquet('BTCUSDT_1h_2024.parquet')
```

### 3.2 数据库存储（适合中大规模）

**时序数据库（推荐 InfluxDB 或 TimescaleDB）**：
```sql
-- TimescaleDB 建表示例
CREATE TABLE klines (
    time        TIMESTAMPTZ NOT NULL,
    symbol      TEXT NOT NULL,
    interval    TEXT NOT NULL,
    open        DOUBLE PRECISION,
    high        DOUBLE PRECISION,
    low         DOUBLE PRECISION,
    close       DOUBLE PRECISION,
    volume      DOUBLE PRECISION
);

-- 创建超表（TimescaleDB 特有）
SELECT create_hypertable('klines', 'time');
```

---

## 四、实时数据流处理

### 4.1 WebSocket 数据流架构

```
Binance WebSocket
      ↓
数据接收层（asyncio）
      ↓
数据解析与验证
      ↓
指标实时计算
      ↓
信号生成
      ↓
订单执行
```

### 4.2 Python 实现示例

```python
import asyncio
import websockets
import json
from collections import deque

class RealtimeDataFeed:
    def __init__(self, symbol: str, interval: str, max_candles: int = 500):
        self.symbol = symbol.lower()
        self.interval = interval
        self.candles = deque(maxlen=max_candles)
        self.ws_url = f"wss://stream.binance.com:9443/ws/{self.symbol}@kline_{interval}"
    
    async def connect(self):
        async with websockets.connect(self.ws_url) as ws:
            async for message in ws:
                data = json.loads(message)
                kline = data['k']
                
                candle = {
                    'time': kline['t'] // 1000,
                    'open': float(kline['o']),
                    'high': float(kline['h']),
                    'low': float(kline['l']),
                    'close': float(kline['c']),
                    'volume': float(kline['v']),
                    'is_closed': kline['x']  # K 线是否已收盘
                }
                
                if candle['is_closed']:
                    self.candles.append(candle)
                    await self.on_candle_closed(candle)
    
    async def on_candle_closed(self, candle: dict):
        """K 线收盘后触发信号计算"""
        # 在此调用指标计算和信号生成逻辑
        pass
```

---

## 五、数据质量检查清单

在将数据用于回测或实盘之前，务必完成以下检查：

- [ ] 数据时间范围是否覆盖目标回测区间
- [ ] 是否存在缺失 K 线（检查时间戳连续性）
- [ ] 成交量是否存在异常值（刷量）
- [ ] 价格是否经过复权处理（如有分叉或重组）
- [ ] 时区是否统一（建议使用 UTC）
- [ ] 数据精度是否足够（小数位数）
- [ ] 是否存在"未来数据泄露"（look-ahead bias）

---

## 参考资料

- Binance API 文档：https://binance-docs.github.io/apidocs/spot/en/
- Glassnode 链上指标：https://glassnode.com/metrics
- Coinglass 衍生品数据：https://www.coinglass.com/
- Alternative.me 恐惧贪婪指数：https://alternative.me/crypto/fear-and-greed-index/

---

## 附录：数据说明与补充

本文档旨在对核心的数据采集与处理流程进行深化和扩展，提供更详尽的数据规范、计算公式、应用场景及常见误区，以帮助量化研究员和开发者更精确、高效地利用各类数据。

### 一、核心指标数据说明与应用

为了确保数据在不同策略和模型中的一致性和准确性，我们对文档中提到的核心指标提供标准化的说明。

#### 1.1 链上指标 (On-Chain Metrics)

链上数据为市场宏观状态提供了独特的视角。以下是对关键链上指标的详细阐述。

| 指标名称 | 计算公式 (LaTeX) | 数据范围与单位 | 精度要求 | 数据来源 |
| :--- | :--- | :--- | :--- | :--- |
| **SOPR** | $SOPR = \frac{\sum P_{\text{realized}}}{\sum P_{\text{created}}}$ | 无单位比率, 通常在 0.9-1.2 波动 | 4 位小数 | Glassnode, CryptoQuant |
| **MVRV** | $MVRV = \frac{\text{Market Value}}{\text{Realized Value}}$ | 无单位比率, 通常在 0.5-4.0 波动 | 4 位小数 | Glassnode, CoinMetrics |
| **交易所净流入** | $V_{\text{inflow}} - V_{\text{outflow}}$ | 交易对的币种单位 (如 BTC, ETH) | 8 位小数 | 各大交易所, Nansen |

**使用场景补充**:

*   **SOPR (已实现利润比率)**: 
    1.  **趋势确认**: 在上升趋势中，SOPR 持续大于 1 且在回调中能迅速反弹至 1 以上，表明市场信心强劲，投资者倾向于持有而非亏本卖出，是趋势健康的信号。
    2.  **熊市底部识别**: 当 SOPR 长时间处于 1 以下，表明市场处于持续亏损状态。若 SOPR 出现向上突破 1 的迹象，可能预示着市场恐慌情绪的终结和底部的形成。

*   **MVRV (市值/已实现价值)**: 
    1.  **宏观周期定位**: MVRV Z-Score（MVRV 的标准化版本）是判断市场处于周期顶/底部的经典工具。Z-Score 进入红色区域（>7）通常对应历史牛市顶部，进入绿色区域（<0）则对应历史熊市底部，可用于长线仓位的建立或退出。
    2.  **价值投资参考**: 将 MVRV 比率视为资产的“估值倍数”。当 MVRV 远低于其历史均值（如低于 1）时，可以认为当前市值相对其“链上成本基础”处于低估状态，为价值投资者提供了潜在的入场机会。

#### 1.2 衍生品数据 (Derivatives Data)

衍生品数据反映了市场杠杆水平和投机情绪，是短期价格波动的重要驱动因素。

| 指标名称 | 计算公式 (概念) | 数据范围与单位 | 精度要求 | 数据来源 |
| :--- | :--- | :--- | :--- | :--- |
| **资金费率** | $Premium + clamp(Interest - Premium, \pm 0.05\%)$ | 百分比 (%), 通常在 ±0.1% 波动 | 6 位小数 | 各大交易所 API |
| **未平仓合约** | $\sum \text{Contracts}_{\text{open}}$ | 美元 (USD) 或币本位 (如 BTC) | 2 位小数 (USD) | 各大交易所 API, Coinglass |

**使用场景补充**:

*   **资金费率 (Funding Rate)**:
    1.  **费率套利策略**: 当不同交易所或不同合约（如 U本位 vs. 币本位）之间出现显著的资金费率差异时，可以通过在费率高的一方做空、费率低的一方做多，来赚取稳定的费率差，这是一种低风险的套利策略。
    2.  **市场情绪极值反转**: 当资金费率达到极端正值（如 >0.1%），表明市场杠杆做多情绪极度狂热，此时价格对负面消息异常敏感，是潜在的短线回调甚至反转的信号。反之，极端负费率则可能是空头陷阱和轧空行情的预兆。

*   **未平仓合约 (Open Interest)**:
    1.  **趋势强度验证**: “价涨量增”是经典的多头趋势确认信号。若价格上涨的同时，[未平仓合约](../../wiki/名词解释/未平仓合约.md)也稳步增加，说明有新资金持续入场做多，趋势较为健康。反之，若价格上涨但 OI 下降，则可能是空头回补驱动的，上涨动力不足。
    2.  **拥挤交易识别**: 当价格在关键阻力位附近横盘，而 OI 却异常快速地增长，这可能意味着多空双方在此处大量建仓，形成“拥挤交易”。一旦价格突破，很可能引发大规模的止损和清算，导致剧烈波动。

### 二、数据格式与参数参考

#### 2.1 数据格式规范

标准化的数据格式是保证数据处理流程稳健性的基石。所有时间序列数据应遵循统一的结构。

**K线 (Kline/Candlestick) 数据格式**:

推荐使用 JSON 数组或 Parquet 文件存储，单条 K 线数据结构如下：

```json
{
  "timestamp": 1672531200000,       // Unix 时间戳 (毫秒, UTC)
  "open": 16500.00,                 // 开盘价 (浮点数)
  "high": 16550.50,                 // 最高价 (浮点数)
  "low": 16480.25,                  // 最低价 (浮点数)
  "close": 16530.75,                // 收盘价 (浮点数)
  "volume": 12345.678,              // 成交量 (以基础资产计, 如 BTC)
  "turnover": 204089123.45          // 成交额 (以计价资产计, 如 USDT)
}
```

*   **时间戳**: 必须为 UTC 时区的 Unix 时间戳（毫秒级），以避免任何时区混淆。处理时建议统一转换为 `datetime` 对象。
*   **价格精度**: 价格字段应使用 `Decimal` 类型或高精度浮点数（`float64`）进行存储和计算，避免浮点数精度损失问题。
*   **成交量/额**: 根据交易所提供的单位进行存储，通常成交量为币的数量，成交额为计价货币的金额。

#### 2.2 数据清洗参数参考表

在 `clean_kline_data` 函数中，部分参数是可调的，其选择会影响清洗效果。下表给出了推荐值与合理范围。

| 参数 | 描述 | 推荐值 | 取值范围 | 调整建议 |
| :--- | :--- | :--- | :--- | :--- |
| `rolling_window` | 用于计算成交量均值和标准差的滚动窗口大小 | 100 | 30 - 200 | 对于高频数据或波动剧烈的市场，可适当减小窗口；对于低频数据，可增大窗口。 |
| `std_multiplier` | 判断成交量为异常值的标准差倍数 | 5 | 3 - 10 | 较小的值会过滤掉更多数据，可能误伤正常波动；较大的值则可能放过一些刷量数据。 |

### 三、常见误区与正确理解

1.  **误区：数据越多越好**
    *   **正确理解**：数据的质量远比数量重要。包含大量噪声、错误或不一致性的数据会严重误导模型训练和策略回测。应将重心放在数据清洗、验证和交叉比对上，而非盲目追求更长的时间跨度或更高的数据频率。

2.  **误区：资金费率为正就代表市场看涨**
    *   **正确理解**：资金费率主要反映的是永续合约价格与现货价格之间的基差。虽然持续为正通常与多头情绪相关，但也可能是由套利者（做多现货、做空永续）驱动的。必须结合[未平仓合约](../../wiki/名词解释/未平仓合约.md)、价格趋势和成交量综合判断，单一依赖资金费率容易产生误判。

3.  **误区：可以直接使用交易所 API 返回的 K 线**
    *   **正确理解**：交易所 API 返回的数据可能存在空缺（如服务器维护）、错误（如价格为0）或逻辑矛盾（如最高价低于最低价）。直接使用这些原始数据进行回测，会导致策略表现严重失真。如文档中 `clean_kline_data` 函数所示，严格的清洗流程是不可或缺的一步。

4.  **误区：回测中的高收益能直接转化为实盘利润**
    *   **正确理解**：回测与实盘存在巨大鸿沟。滑点、交易延迟、API 限制、流动性差异以及“未来数据泄露”等问题都会侵蚀理论收益。在数据处理阶段，必须警惕[未来函数](../../wiki/名词解释/未来函数.md)（如使用当日收盘价计算开盘时的信号），并为回测增加保守的交易成本假设。

5.  **误区：链上数据可以精确预测价格**
    *   **正确理解**：链上数据（如 [SOPR](../../wiki/名词解释/SOPR.md)、[MVRV](../../wiki/名词解释/MVRV.md)）是反映市场宏观状态和长期投资者行为的“慢变量”，对于判断市场周期和情绪拐点有重要价值，但对短期价格波动的预测能力有限。应将其作为宏观过滤器或辅助决策工具，而非高频交易信号。