# 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