# 需求：资金面数据（data_provider → chan）

**提出方：** chan  
**执行方：** data_provider  
**阶段：** Paper。先看效果。不进 Live。

---

## 要什么

chan 要在缠论图上叠资金面，和现有 K 线对得上。

data_provider 对外提供资金面；chan **只从 data_provider 取**，不访问交易所，不访问 CoinGlass。

K 线路径不动（现有 `/api/candles` 与 K 线推送）。本次只加资金面。

---

## 数据

先三个币：**BTC、ETH、SOL**（USDT 永续，符号与现有 K 线相同，如 `BTC/USDT:USDT`）。

要两样：

1. **持仓量（OI）**  
   - 要历史，能覆盖缠论常用周期：`15m`、`30m`、`4h`、`1d`（有 `1h`/`2h` 更好）。  
   - 要当前最新值。  
   - 历史长度至少约 30 天。

2. **资金费率（funding）**  
   - 要当前值。  
   - 要历史结算序列。  
   - 对齐到各周期 K 线：结算点落到所在那根；非结算 bar 沿用上一次结算值，不要插值编造。

来源：交易所公开数据即可，本阶段不买 CoinGlass。OI 历史哪家所没有，用另一家所公开数据补，需标明来源。

**本阶段不要：** 清算、热力图、多空比、订单簿、CoinGlass。

---

## 给 chan 的接口

与 `/api/candles` 同一套约定：

- `symbol` 与蜡烛相同  
- 时间戳毫秒 UTC  
- 按周期 `tf` 取序列  
- 支持 `start` / `end` / `limit`（默认 `limit=500`）

示例：

```http
GET /api/deriv?symbol=BTC/USDT:USDT&tf=15m&metrics=oi,funding
```

每根：

| 字段 | 要求 |
|---|---|
| `timestamp` | 与同 `tf` 的 `/api/candles` **开盘时间**对齐；对不齐的不要 |
| `oi` | 该 bar 持仓量；缺则 `null` |
| `oi_src` | 该值来自哪家所 |
| `funding` | 该 bar 资金费率；缺则 `null` |
| `funding_src` | 该值来自哪家所 |

健康状态要能看出：资金面是否可用、各所是否通、上次成功时间。

---

## 约束

- 全程 HTTPS REST。本阶段不要求资金面 WebSocket。  
- chan、浏览器不得直连交易所。  
- 现有 K 线接口行为不变。  
- 一家所挂了：缺那家字段，另一家仍要能出；两边都没有且无可用数据时明确失败。  
- 上游限流或超时：不要拖垮 K 线。

---

## 不算本次

- CoinGlass / 付费数据  
- 清算、热力、多空  
- Live、下单  
- chan 叠图（等本接口可用再做）

---

## 怎样算齐

1. `GET /api/deriv?symbol=BTC/USDT:USDT&tf=15m` 能拿到 `oi`、`funding`，时间能对上同参数的 `/api/candles`。  
2. chan / 浏览器零次访问交易所。  
3. 只挂一家所时，接口仍可用，只缺对应字段。  
4. K 线不受影响。