laoxong/nofx
1
0
Fork 0
mirror of https://github.com/laoxong/nofx.git synced 2026-06-04 09:58:22 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: add quant data plugin API documentation

Browse Source
This commit is contained in:
tinkle-community
2025-12-08 12:42:26 +08:00
parent 24717d8589
commit ce3f62cb50
2 changed files with 604 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/api/coin_api.md
+350
View File
@@ -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. **资金流向解读**：机构与散户的资金流向通常呈相反趋势，可作为市场情绪判断依据
docs/api/oi_api.md
+254
View File
@@ -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