diff --git a/docs/api/coin_api.md b/docs/api/coin_api.md
new file mode 100644
index 00000000..12d69b48
--- /dev/null
+++ b/docs/api/coin_api.md
@@ -0,0 +1,350 @@
+# 币种综合数据接口文档
+
+## 接口概述
+
+该接口提供单个币种的综合数据查询，一次请求即可获取资金净流入、持仓变化、价格变化等多维度数据。
+
+## 请求信息
+
+### 接口地址
+
+```
+GET /api/coin/{symbol}
+```
+
+### 完整示例
+
+```
+http://nofxaios.com:30006/api/coin/PIPPINUSDT?include=netflow,oi,price&auth=cm_568c67eae410d912c54c
+```
+
+### 请求参数
+
+| 参数 | 位置 | 类型 | 必填 | 说明 |
+|-----|------|------|-----|------|
+| symbol | path | string | 是 | 币种符号，如 `PIPPINUSDT`、`ETH`（会自动补全USDT后缀） |
+| include | query | string | 否 | 返回数据类型，逗号分隔。可选值：`netflow,oi,price`。默认返回全部 |
+| auth | query | string | 是 | 认证密钥 |
+
+### include 参数说明
+
+| 值 | 说明 |
+|---|------|
+| netflow | 资金净流入数据（机构/散户、合约/现货） |
+| oi | 持仓数据（币安、Bybit） |
+| price | 价格变化百分比 |
+
+---
+
+## 返回数据
+
+### 完整响应示例
+
+```json
+{
+  "code": 0,
+  "data": {
+    "symbol": "PIPPINUSDT",
+    "price": 0.085,
+    "netflow": {
+      "institution": {
+        "future": {
+          "1m": 120000,
+          "5m": 580000,
+          "15m": 1200000,
+          "30m": 2500000,
+          "1h": 5800000,
+          "4h": 12000000,
+          "8h": 25000000,
+          "12h": 38000000,
+          "24h": 65000000,
+          "2d": 120000000,
+          "3d": 180000000
+        },
+        "spot": {
+          "1m": 50000,
+          "5m": 280000,
+          "15m": 600000,
+          "30m": 1200000,
+          "1h": 2800000,
+          "4h": 6000000,
+          "8h": 12000000,
+          "12h": 18000000,
+          "24h": 32000000,
+          "2d": 60000000,
+          "3d": 90000000
+        }
+      },
+      "personal": {
+        "future": {
+          "1m": -80000,
+          "5m": -350000,
+          "15m": -800000,
+          "30m": -1500000,
+          "1h": -3200000,
+          "4h": -8000000,
+          "8h": -15000000,
+          "12h": -22000000,
+          "24h": -40000000,
+          "2d": -75000000,
+          "3d": -110000000
+        },
+        "spot": {
+          "1m": -30000,
+          "5m": -150000,
+          "15m": -400000,
+          "30m": -800000,
+          "1h": -1800000,
+          "4h": -4000000,
+          "8h": -8000000,
+          "12h": -12000000,
+          "24h": -22000000,
+          "2d": -40000000,
+          "3d": -60000000
+        }
+      }
+    },
+    "oi": {
+      "binance": {
+        "current_oi": 85000,
+        "net_long": 48000,
+        "net_short": 37000,
+        "delta": {
+          "1m": {
+            "oi_delta": 150,
+            "oi_delta_value": 14550000,
+            "oi_delta_percent": 0.18
+          },
+          "5m": {
+            "oi_delta": 680,
+            "oi_delta_value": 65960000,
+            "oi_delta_percent": 0.8
+          },
+          "1h": {
+            "oi_delta": 2500,
+            "oi_delta_value": 242500000,
+            "oi_delta_percent": 2.94
+          },
+          "4h": {
+            "oi_delta": 5200,
+            "oi_delta_value": 504400000,
+            "oi_delta_percent": 6.12
+          },
+          "24h": {
+            "oi_delta": 8500,
+            "oi_delta_value": 824500000,
+            "oi_delta_percent": 10.0
+          }
+        }
+      },
+      "bybit": {
+        "current_oi": 42000,
+        "net_long": 24000,
+        "net_short": 18000,
+        "delta": {
+          "1h": {
+            "oi_delta": 1200,
+            "oi_delta_value": 116400000,
+            "oi_delta_percent": 2.86
+          }
+        }
+      }
+    },
+    "price_change": {
+      "1m": 0.05,
+      "5m": 0.18,
+      "15m": 0.35,
+      "30m": 0.62,
+      "1h": 1.25,
+      "4h": 2.80,
+      "8h": 3.50,
+      "12h": 2.95,
+      "24h": 4.80,
+      "2d": 6.50,
+      "3d": 8.20
+    }
+  }
+}
+```
+
+---
+
+## 字段详细说明
+
+### 基础字段
+
+| 字段 | 类型 | 说明 |
+|-----|------|------|
+| symbol | string | 币种交易对，如 `PIPPINUSDT` |
+| price | float | 当前期货价格（单位：USDT） |
+
+---
+
+### netflow - 资金净流入
+
+资金净流入数据，**正数表示资金流入，负数表示资金流出**，单位为 USDT。
+
+#### 数据结构
+
+```
+netflow
+├── institution          # 机构资金
+│   ├── future          # 合约市场
+│   └── spot            # 现货市场
+└── personal            # 散户资金
+    ├── future          # 合约市场
+    └── spot            # 现货市场
+```
+
+#### 分类说明
+
+| 字段 | 说明 |
+|-----|------|
+| institution.future | 机构在合约市场的资金净流入 |
+| institution.spot | 机构在现货市场的资金净流入 |
+| personal.future | 散户在合约市场的资金净流入 |
+| personal.spot | 散户在现货市场的资金净流入 |
+
+#### 时间周期
+
+| 字段 | 说明 |
+|-----|------|
+| 1m | 最近 1 分钟 |
+| 5m | 最近 5 分钟 |
+| 15m | 最近 15 分钟 |
+| 30m | 最近 30 分钟 |
+| 1h | 最近 1 小时 |
+| 4h | 最近 4 小时 |
+| 8h | 最近 8 小时 |
+| 12h | 最近 12 小时 |
+| 24h | 最近 24 小时 |
+| 2d | 最近 2 天 |
+| 3d | 最近 3 天 |
+
+#### 使用建议
+
+- **机构资金流入 + 散户资金流出** = 典型的主力吸筹信号
+- **机构资金流出 + 散户资金流入** = 典型的主力出货信号
+- 关注 **合约与现货的资金流向是否一致**，判断市场情绪
+
+---
+
+### oi - 持仓数据
+
+持仓量（Open Interest）数据，来源于币安和 Bybit 交易所。
+
+#### 字段说明
+
+| 字段 | 类型 | 说明 |
+|-----|------|------|
+| current_oi | float | 当前总持仓量（单位：币） |
+| net_long | float | 净多头持仓量 |
+| net_short | float | 净空头持仓量 |
+| delta | object | 各时间周期的持仓变化 |
+
+#### delta 子字段
+
+| 字段 | 类型 | 说明 |
+|-----|------|------|
+| oi_delta | float | 持仓量变化（单位：币） |
+| oi_delta_value | float | 持仓价值变化（单位：USDT） |
+| oi_delta_percent | float | 持仓量变化百分比（%） |
+
+#### 使用建议
+
+- **持仓量增加 + 价格上涨** = 多头主导，趋势可能延续
+- **持仓量增加 + 价格下跌** = 空头主导，下跌趋势可能延续
+- **持仓量减少 + 价格变化** = 平仓为主，趋势可能反转
+- **net_long > net_short** = 市场整体偏多
+
+---
+
+### price_change - 价格变化
+
+各时间周期的价格涨跌幅，**单位为百分比（%）**，正数表示上涨，负数表示下跌。
+
+| 字段 | 说明 |
+|-----|------|
+| 1m | 最近 1 分钟涨跌幅 |
+| 5m | 最近 5 分钟涨跌幅 |
+| 15m | 最近 15 分钟涨跌幅 |
+| 30m | 最近 30 分钟涨跌幅 |
+| 1h | 最近 1 小时涨跌幅 |
+| 4h | 最近 4 小时涨跌幅 |
+| 8h | 最近 8 小时涨跌幅 |
+| 12h | 最近 12 小时涨跌幅 |
+| 24h | 最近 24 小时涨跌幅 |
+| 2d | 最近 2 天涨跌幅 |
+| 3d | 最近 3 天涨跌幅 |
+
+---
+
+## 错误响应
+
+| code | 说明 |
+|------|------|
+| 0 | 成功 |
+| 400 | 参数错误（如缺少 symbol） |
+| 401 | 认证失败（auth 无效） |
+| 500 | 服务器内部错误 |
+
+错误响应示例：
+
+```json
+{
+  "code": 400,
+  "message": "symbol parameter is required"
+}
+```
+
+---
+
+## 调用示例
+
+### cURL
+
+```bash
+curl -X GET "http://nofxaios.com:30006/api/coin/PIPPINUSDT?include=netflow,oi,price&auth=cm_568c67eae410d912c54c"
+```
+
+### Python
+
+```python
+import requests
+
+url = "http://nofxaios.com:30006/api/coin/PIPPINUSDT"
+params = {
+    "include": "netflow,oi,price",
+    "auth": "cm_568c67eae410d912c54c"
+}
+
+response = requests.get(url, params=params)
+data = response.json()
+
+print(f"当前价格: {data['data']['price']}")
+print(f"1小时机构合约净流入: {data['data']['netflow']['institution']['future']['1h']}")
+print(f"24小时价格涨跌幅: {data['data']['price_change']['24h']}%")
+```
+
+### JavaScript
+
+```javascript
+const url = 'http://nofxaios.com:30006/api/coin/PIPPINUSDT?include=netflow,oi,price&auth=cm_568c67eae410d912c54c';
+
+fetch(url)
+  .then(response => response.json())
+  .then(data => {
+    console.log('当前价格:', data.data.price);
+    console.log('1小时机构合约净流入:', data.data.netflow.institution.future['1h']);
+    console.log('24小时价格涨跌幅:', data.data.price_change['24h'], '%');
+  });
+```
+
+---
+
+## 注意事项
+
+1. **symbol 参数**：支持带或不带 `USDT` 后缀，如 `PIPPIN` 和 `PIPPINUSDT` 等效
+2. **include 参数**：可按需选择返回数据，减少不必要的数据传输
+3. **数据更新频率**：数据实时更新，建议轮询间隔不低于 1 秒
+4. **资金流向解读**：机构与散户的资金流向通常呈相反趋势，可作为市场情绪判断依据
diff --git a/docs/api/oi_api.md b/docs/api/oi_api.md
new file mode 100644
index 00000000..07d8d861
--- /dev/null
+++ b/docs/api/oi_api.md
@@ -0,0 +1,254 @@
+# OI 持仓数据接口文档
+
+## 接口概述
+
+该接口提供币安交易所的合约持仓量（Open Interest）排行数据，支持查询持仓增加和减少排行榜。
+
+## 接口列表
+
+| 接口 | 说明 |
+|-----|------|
+| `/api/oi/top` | 持仓增加排行 Top20（固定参数，向后兼容） |
+| `/api/oi/top-ranking` | 持仓增加排行（支持自定义参数） |
+| `/api/oi/low-ranking` | 持仓减少排行（支持自定义参数） |
+
+---
+
+## 1. 持仓增加排行 Top20
+
+### 请求
+
+```
+GET /api/oi/top
+```
+
+### 完整示例
+
+```
+http://nofxaios.com:30006/api/oi/top?auth=cm_568c67eae410d912c54c
+```
+
+### 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|-----|------|-----|------|
+| auth | string | 是 | 认证密钥 |
+
+### 说明
+
+固定返回 1 小时内持仓价值增加最多的前 20 个币种，向后兼容接口。
+
+---
+
+## 2. 持仓增加排行（自定义参数）
+
+### 请求
+
+```
+GET /api/oi/top-ranking
+```
+
+### 完整示例
+
+```
+http://nofxaios.com:30006/api/oi/top-ranking?limit=50&duration=4h&auth=cm_568c67eae410d912c54c
+```
+
+### 参数
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|-----|------|-----|-------|------|
+| limit | int | 否 | 20 | 获取数量，范围 1-100 |
+| duration | string | 否 | 1h | 时间范围 |
+| auth | string | 是 | - | 认证密钥 |
+
+---
+
+## 3. 持仓减少排行
+
+### 请求
+
+```
+GET /api/oi/low-ranking
+```
+
+### 完整示例
+
+```
+http://nofxaios.com:30006/api/oi/low-ranking?limit=30&duration=24h&auth=cm_568c67eae410d912c54c
+```
+
+### 参数
+
+同持仓增加排行接口。
+
+---
+
+## duration 时间范围参数
+
+| 值 | 说明 |
+|---|------|
+| 1m | 1 分钟 |
+| 5m | 5 分钟 |
+| 15m | 15 分钟 |
+| 30m | 30 分钟 |
+| 1h | 1 小时（默认） |
+| 4h | 4 小时 |
+| 8h | 8 小时 |
+| 12h | 12 小时 |
+| 24h | 24 小时 |
+| 1d | 1 天（同 24h） |
+| 2d | 2 天 |
+| 3d | 3 天 |
+
+---
+
+## 返回数据
+
+### 响应示例
+
+```json
+{
+  "code": 0,
+  "data": {
+    "count": 20,
+    "exchange": "binance",
+    "time_range": "4小时",
+    "time_range_param": "4h",
+    "rank_type": "top",
+    "limit": 20,
+    "positions": [
+      {
+        "rank": 1,
+        "symbol": "BTCUSDT",
+        "oi_delta": 1500.5,
+        "oi_delta_value": 145500000,
+        "oi_delta_percent": 3.52,
+        "current_oi": 44000,
+        "price_delta_percent": 2.15,
+        "net_long": 26000,
+        "net_short": 18000
+      },
+      {
+        "rank": 2,
+        "symbol": "ETHUSDT",
+        "oi_delta": 25000,
+        "oi_delta_value": 87500000,
+        "oi_delta_percent": 2.85,
+        "current_oi": 900000,
+        "price_delta_percent": 1.80,
+        "net_long": 520000,
+        "net_short": 380000
+      }
+    ]
+  }
+}
+```
+
+### 字段说明
+
+#### 外层字段
+
+| 字段 | 类型 | 说明 |
+|-----|------|------|
+| count | int | 返回的币种数量 |
+| exchange | string | 交易所，固定为 `binance` |
+| time_range | string | 时间范围显示名称 |
+| time_range_param | string | 时间范围参数值 |
+| rank_type | string | 排行类型：`top` 增加 / `low` 减少 |
+| limit | int | 请求的数量限制 |
+| positions | array | 持仓数据列表 |
+
+#### positions 数组字段
+
+| 字段 | 类型 | 说明 |
+|-----|------|------|
+| rank | int | 排名 |
+| symbol | string | 币种交易对，如 `BTCUSDT` |
+| oi_delta | float | 持仓量变化（单位：币） |
+| oi_delta_value | float | 持仓价值变化（单位：USDT），**排序依据** |
+| oi_delta_percent | float | 持仓量变化百分比（%） |
+| current_oi | float | 当前持仓量（单位：币） |
+| price_delta_percent | float | 价格变化百分比（%） |
+| net_long | float | 净多头持仓量 |
+| net_short | float | 净空头持仓量 |
+
+---
+
+## 数据解读
+
+### 持仓量与价格的关系
+
+| 持仓变化 | 价格变化 | 市场含义 |
+|---------|---------|---------|
+| 增加 | 上涨 | 多头主导，上涨趋势可能延续 |
+| 增加 | 下跌 | 空头主导，下跌趋势可能延续 |
+| 减少 | 上涨 | 空头平仓，可能是反弹 |
+| 减少 | 下跌 | 多头平仓，可能是回调 |
+
+### 多空比例
+
+- `net_long > net_short`：市场整体偏多
+- `net_long < net_short`：市场整体偏空
+
+---
+
+## 调用示例
+
+### cURL
+
+```bash
+curl -X GET "http://nofxaios.com:30006/api/oi/top-ranking?limit=50&duration=4h&auth=cm_568c67eae410d912c54c"
+```
+
+### Python
+
+```python
+import requests
+
+url = "http://nofxaios.com:30006/api/oi/top-ranking"
+params = {
+    "limit": 50,
+    "duration": "4h",
+    "auth": "cm_568c67eae410d912c54c"
+}
+
+response = requests.get(url, params=params)
+data = response.json()
+
+for pos in data['data']['positions']:
+    print(f"#{pos['rank']} {pos['symbol']}: 持仓价值变化 ${pos['oi_delta_value']:,.0f}")
+```
+
+### JavaScript
+
+```javascript
+const url = 'http://nofxaios.com:30006/api/oi/top-ranking?limit=50&duration=4h&auth=cm_568c67eae410d912c54c';
+
+fetch(url)
+  .then(response => response.json())
+  .then(data => {
+    data.data.positions.forEach(pos => {
+      console.log(`#${pos.rank} ${pos.symbol}: 持仓价值变化 $${pos.oi_delta_value.toLocaleString()}`);
+    });
+  });
+```
+
+---
+
+## 错误响应
+
+| code | 说明 |
+|------|------|
+| 0 | 成功 |
+| 401 | 认证失败（auth 无效） |
+| 500 | 服务器内部错误 |
+
+---
+
+## 注意事项
+
+1. 数据来源为币安交易所
+2. 排行依据为 `oi_delta_value`（持仓价值变化），非持仓量变化
+3. 数据缓存 2 秒，高频请求会命中缓存
+4. `limit` 最大值为 100