liuyu/nofx
1
0
Fork 0
mirror of https://github.com/NoFxAiOS/nofx.git synced 2026-06-06 05:51:19 +08:00
Code Issues Packages Projects Releases Wiki Activity

feat: unify NofxOS data provider and fix language consistency

Browse Source 
- Add unified NofxOS API key configuration in IndicatorEditor
- Add language field to StrategyConfig for consistent prompt generation
- Auto-update prompt sections when interface language changes
- Remove scattered URL inputs from CoinSourceEditor and IndicatorEditor
- Create nofxos provider package with formatted data output
- Update kernel engine to use config-based language setting
This commit is contained in:
tinkle-community
2026-01-04 00:59:07 +08:00
parent 13fda47151
commit 0275e23b7e
32 changed files with 3029 additions and 1767 deletions
Download Patch File Download Diff File Expand all files Collapse all files

852
docs/api/API_REFERENCE.md Normal file
View File

@@ -0,0 +1,852 @@
# CryptoMaster API 接口文档
## 概述
### 基础信息
- **Base URL**: `https://nofxos.ai`
- **响应格式**: JSON
- **缓存时间**: 15秒（所有数据接口）
- **限流**: 每个IP每秒最多30次请求
### 认证方式
所有数据接口需要认证，支持两种方式：
#### 方式1: Query参数（推荐）
```
GET /api/ai500/list?auth=your_api_key
```
#### 方式2: Authorization Header
```
GET /api/ai500/list
Authorization: Bearer your_api_key
```
### 响应格式
**成功响应：**
```json
{
"success": true,
"data": { ... }
}
```
**错误响应：**
```json
{
"success": false,
"error": "错误信息"
}
```
---
## 重要：数值格式说明
### 百分比字段格式
不同接口的百分比字段使用不同的格式，请注意区分：
| 字段名 | 格式 | 示例 | 说明 |
|--------|------|------|------|
| `price_delta` (涨跌幅榜/币种详情) | **小数** | `0.05` = 5% | 需要 ×100 转换为百分比 |
| `oi_delta_percent` | **已×100** | `5.0` = 5% | 直接使用，无需转换 |
| `price_delta_percent` (OI接口) | **已×100** | `5.0` = 5% | 直接使用，无需转换 |
| `increase_percent` (AI500) | **已×100** | `7.14` = 7.14% | 直接使用，无需转换 |
### 金额字段
| 字段名 | 单位 | 说明 |
|--------|------|------|
| `oi_delta_value` | USDT | 持仓价值变化 |
| `amount` / `future_flow` / `spot_flow` | USDT | 资金流量 |
| `price` | USDT | 当前价格 |
### 持仓量字段
| 字段名 | 单位 | 说明 |
|--------|------|------|
| `oi_delta` | 张/个 | 持仓量变化 |
| `current_oi` / `oi` | 张/个 | 当前持仓量 |
| `net_long` / `net_short` | 张/个 | 净多头/空头持仓 |
---
## 时间范围参数说明
所有接口支持的 `duration` 参数值：
| 参数值 | 说明 | 备注 |
|--------|------|------|
| `1m` | 1分钟 | |
| `5m` | 5分钟 | |
| `15m` | 15分钟 | |
| `30m` | 30分钟 | |
| `1h` | 1小时 | 默认值 |
| `4h` | 4小时 | |
| `8h` | 8小时 | |
| `12h` | 12小时 | |
| `24h` / `1d` | 24小时 | 两种写法均可 |
| `2d` | 2天 | |
| `3d` | 3天 | |
| `5d` | 5天 | |
| `7d` | 7天 | |
---
## 1. AI500 智能评分接口
AI500 是基于多维度量化指标的智能评分系统，用于筛选具有上涨潜力的币种。
### 1.1 获取AI500推荐币种列表
获取经过严格筛选的优质币种列表。
**请求**
```
GET /api/ai500/list
```
**过滤条件**
- AI评分 > 70
- 币安OI持仓价值 > 15M USDT
- 现价 > 上榜起始价格（只返回上涨中的币种）
- 资金没有持续流出（1h/4h/12h/24h不能全为负）
**响应示例**
```json
{
"success": true,
"data": {
"count": 5,
"coins": [
{
"pair": "BTCUSDT",
"score": 85.234,
"start_time": 1704067200,
"start_price": 42000.5,
"last_score": 83.5,
"max_score": 87.2,
"max_price": 45000.0,
"increase_percent": 7.14
}
]
}
}
```
**字段说明**
| 字段 | 类型 | 说明 |
|------|------|------|
| `pair` | string | 交易对名称，如 BTCUSDT |
| `score` | float | 当前AI评分（0-100） |
| `start_time` | int64 | 上榜时间戳（Unix秒） |
| `start_price` | float | 上榜时价格（USDT） |
| `last_score` | float | 上次记录的评分 |
| `max_score` | float | 在榜期间最高评分 |
| `max_price` | float | 在榜期间最高价格（USDT） |
| `increase_percent` | float | 最大涨幅百分比（**已×100**，7.14 = 7.14%） |
---
### 1.2 获取单个币种AI500信息
**请求**
```
GET /api/ai500/:symbol
```
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `symbol` | string | 是 | 币种符号，支持 `BTCUSDT` 或 `BTC` 格式 |
**示例**
```
GET /api/ai500/BTC
GET /api/ai500/ETHUSDT
```
**响应示例**
```json
{
"success": true,
"data": {
"info": {
"pair": "BTCUSDT",
"score": 85.234,
"start_time": 1704067200,
"start_price": 42000.5,
"last_score": 83.5,
"max_score": 87.2,
"max_price": 45000.0,
"increase_percent": 7.14
},
"current_price": 44500.0,
"score": 85.234
}
}
```
---
### 1.3 获取AI500统计信息
获取AI500整体统计数据。
**请求**
```
GET /api/ai500/stats
```
**响应示例**
```json
{
"success": true,
"data": {
"statistics": {
"total_count": 50,
"average_score": 72.5,
"max_score": 95.2,
"min_score": 55.3,
"average_increase": 12.5
},
"top_coins": [...],
"bottom_coins": [...]
}
}
```
---
## 2. 持仓量(OI)排行接口
监控各币种的合约持仓量变化，用于判断市场资金动向。
### 2.1 获取OI增加排行榜
返回持仓价值增加最多的币种排行。
**请求**
```
GET /api/oi/top-ranking
```
**查询参数**
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `limit` | int | 20 | 返回数量，最大100 |
| `duration` | string | `1h` | 时间范围，见[时间范围参数](#时间范围参数说明) |
**示例**
```
GET /api/oi/top-ranking?limit=50&duration=4h
```
**响应示例**
```json
{
"success": true,
"data": {
"count": 20,
"exchange": "binance",
"time_range": "4小时",
"time_range_param": "4h",
"rank_type": "top",
"limit": 50,
"positions": [
{
"rank": 1,
"symbol": "BTCUSDT",
"price": 44500.0,
"oi_delta": 1500.5,
"oi_delta_value": 65000000,
"oi_delta_percent": 2.5,
"current_oi": 62000,
"price_delta_percent": 1.2,
"net_long": 35000,
"net_short": 27000
}
]
}
}
```
**字段说明**
| 字段 | 类型 | 格式 | 说明 |
|------|------|------|------|
| `rank` | int | - | 排名 |
| `symbol` | string | - | 交易对名称 |
| `price` | float | USDT | 当前价格 |
| `oi_delta` | float | 张/个 | 持仓量变化 |
| `oi_delta_value` | float | USDT | 持仓价值变化（**排序依据**） |
| `oi_delta_percent` | float | **已×100** | 持仓量变化百分比，2.5 = 2.5% |
| `current_oi` | float | 张/个 | 当前持仓量 |
| `price_delta_percent` | float | **已×100** | 价格变化百分比，1.2 = 1.2% |
| `net_long` | float | 张/个 | 净多头持仓 |
| `net_short` | float | 张/个 | 净空头持仓 |
---
### 2.2 获取OI减少排行榜
返回持仓价值减少最多的币种排行。
**请求**
```
GET /api/oi/low-ranking
```
**查询参数**
同 [OI增加排行榜](#21-获取oi增加排行榜)
**示例**
```
GET /api/oi/low-ranking?limit=30&duration=24h
```
---
### 2.3 获取OI Top20（向后兼容）
**请求**
```
GET /api/oi/top
```
固定返回1小时内OI增加最多的Top20，用于向后兼容。
---
## 3. 资金流量(NetFlow)排行接口
监控机构和散户的资金流向。
### 3.1 获取资金流入排行榜
**请求**
```
GET /api/netflow/top-ranking
```
**查询参数**
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `limit` | int | 20 | 返回数量，最大100 |
| `duration` | string | `1h` | 时间范围，见[时间范围参数](#时间范围参数说明) |
| `type` | string | `institution` | 资金类型：`institution`(机构), `personal`(散户) |
| `trade` | string | `future` | 交易类型：`future`(合约), `spot`(现货) |
**示例**
```
GET /api/netflow/top-ranking?limit=30&duration=4h&type=institution&trade=future
```
**响应示例**
```json
{
"success": true,
"data": {
"count": 30,
"type": "institution",
"trade": "合约",
"time_range": "4h",
"rank_type": "top",
"limit": 30,
"netflows": [
{
"rank": 1,
"symbol": "BTCUSDT",
"amount": 15000000.5,
"price": 44500.0
}
]
}
}
```
**字段说明**
| 字段 | 类型 | 格式 | 说明 |
|------|------|------|------|
| `rank` | int | - | 排名 |
| `symbol` | string | - | 交易对名称 |
| `amount` | float | USDT | 资金流量，**正数=流入，负数=流出** |
| `price` | float | USDT | 当前价格 |
---
### 3.2 获取资金流出排行榜
**请求**
```
GET /api/netflow/low-ranking
```
**查询参数**
同 [资金流入排行榜](#31-获取资金流入排行榜)
**示例**
```
GET /api/netflow/low-ranking?limit=20&duration=1h&type=personal&trade=spot
```
---
### 3.3 获取资金流入Top20（向后兼容）
**请求**
```
GET /api/netflow/top
```
固定返回1小时内机构合约资金流入最多的Top20。
---
## 4. 涨跌幅榜接口
### 4.1 获取涨跌幅榜
同时返回涨幅榜(top)和跌幅榜(low)，支持多个时间周期同时查询。
**请求**
```
GET /api/price/ranking
```
**查询参数**
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `duration` | string | `1h` | 时间范围，可多选逗号分隔：`1h,4h,24h` |
| `limit` | int | 20 | 每个榜单返回数量，最大100 |
| `exchange` | string | `binance` | 交易所 |
**示例**
```
GET /api/price/ranking?duration=1h,4h,24h&limit=20
```
**响应示例**
```json
{
"success": true,
"data": {
"durations": ["1h", "4h", "24h"],
"limit": 20,
"data": {
"1h": {
"top": [
{
"pair": "MOGUSDT",
"symbol": "MOG",
"price_delta": 0.0723,
"price": 0.00123,
"future_flow": 201500,
"spot_flow": 0,
"oi": 15000000,
"oi_delta": 500000,
"oi_delta_value": 615
}
],
"low": [
{
"pair": "XYZUSDT",
"symbol": "XYZ",
"price_delta": -0.0512,
"price": 1.234,
"future_flow": -50000,
"spot_flow": -10000,
"oi": 8000000,
"oi_delta": -200000,
"oi_delta_value": -246800
}
]
},
"4h": { ... },
"24h": { ... }
}
}
}
```
**字段说明**
| 字段 | 类型 | 格式 | 说明 |
|------|------|------|------|
| `pair` | string | - | 完整交易对名称，如 BTCUSDT |
| `symbol` | string | - | 币种符号（去除USDT），如 BTC |
| `price_delta` | float | **小数** | 价格变动比例，**0.0723 = 7.23%**（需×100显示） |
| `price` | float | USDT | 当前价格 |
| `future_flow` | float | USDT | 合约资金流量，正数=流入 |
| `spot_flow` | float | USDT | 现货资金流量，正数=流入 |
| `oi` | float | 张/个 | 当前持仓量 |
| `oi_delta` | float | 张/个 | 持仓变化量 |
| `oi_delta_value` | float | USDT | 持仓变化价值 |
> **注意**：`price_delta` 使用小数格式，与 OI 接口的 `price_delta_percent` 不同！
---
## 5. 币种详情接口
### 5.1 获取单币种完整数据
获取指定币种的所有统计信息，一次调用获取全部数据。
**请求**
```
GET /api/coin/:symbol
```
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `symbol` | string | 是 | 币种符号，支持 `BTC` 或 `BTCUSDT` 格式 |
**查询参数**
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `include` | string | `netflow,oi,price,ai500` | 包含的数据类型，逗号分隔 |
**include 参数选项**
| 值 | 说明 |
|------|------|
| `netflow` | 资金流量数据（机构/散户，合约/现货） |
| `oi` | 持仓量数据（币安/Bybit） |
| `price` | 价格变化数据 |
| `ai500` | AI500评分 |
**示例**
```
GET /api/coin/BTC?include=netflow,oi,price,ai500
GET /api/coin/ETHUSDT?include=netflow,oi
```
**响应示例**
```json
{
"success": true,
"data": {
"symbol": "BTCUSDT",
"price": 44500.0,
"ai500": {
"score": 85.234,
"is_active": true,
"start_time": 1704067200,
"start_price": 42000.5,
"increase_percent": 5.95
},
"netflow": {
"institution": {
"future": {
"1m": 50000,
"5m": 200000,
"15m": 500000,
"30m": 800000,
"1h": 1500000,
"4h": 5000000,
"8h": 8000000,
"12h": 10000000,
"24h": 15000000,
"2d": 25000000,
"3d": 35000000,
"5d": 50000000,
"7d": 75000000
},
"spot": { ... }
},
"personal": {
"future": { ... },
"spot": { ... }
}
},
"oi": {
"binance": {
"current_oi": 62000,
"net_long": 35000,
"net_short": 27000,
"delta": {
"1m": {
"oi_delta": 50,
"oi_delta_value": 2225000,
"oi_delta_percent": 0.08
},
"5m": { ... },
"1h": { ... },
"4h": { ... },
"24h": { ... }
}
},
"bybit": { ... }
},
"price_change": {
"1m": 0.001,
"5m": 0.005,
"15m": 0.008,
"30m": 0.012,
"1h": 0.015,
"4h": 0.025,
"8h": 0.035,
"12h": 0.042,
"24h": 0.055,
"2d": 0.08,
"3d": 0.12,
"5d": 0.18,
"7d": 0.25
}
}
}
```
**字段说明**
**price_change 对象**
| 字段 | 类型 | 格式 | 说明 |
|------|------|------|------|
| `{duration}` | float | **小数** | 价格变化比例，**0.015 = 1.5%**（需×100显示） |
**netflow 对象**
| 路径 | 类型 | 格式 | 说明 |
|------|------|------|------|
| `institution.future.{duration}` | float | USDT | 机构合约资金流量 |
| `institution.spot.{duration}` | float | USDT | 机构现货资金流量 |
| `personal.future.{duration}` | float | USDT | 散户合约资金流量 |
| `personal.spot.{duration}` | float | USDT | 散户现货资金流量 |
**oi 对象**
| 路径 | 类型 | 格式 | 说明 |
|------|------|------|------|
| `binance.current_oi` | float | 张/个 | 币安当前持仓量 |
| `binance.net_long` | float | 张/个 | 币安净多头 |
| `binance.net_short` | float | 张/个 | 币安净空头 |
| `binance.delta.{duration}.oi_delta` | float | 张/个 | 持仓量变化 |
| `binance.delta.{duration}.oi_delta_value` | float | USDT | 持仓价值变化 |
| `binance.delta.{duration}.oi_delta_percent` | float | **已×100** | 持仓变化百分比，0.08 = 0.08% |
| `bybit.*` | - | - | Bybit数据，结构同上 |
**ai500 对象**
| 字段 | 类型 | 格式 | 说明 |
|------|------|------|------|
| `score` | float | 0-100 | AI综合评分 |
| `is_active` | bool | - | 是否为活跃高分币种 |
| `start_time` | int64 | Unix秒 | 上榜时间 |
| `start_price` | float | USDT | 上榜时价格 |
| `increase_percent` | float | **已×100** | 最大涨幅，5.95 = 5.95% |
---
## 错误码说明
| HTTP状态码 | 说明 | 常见原因 |
|------------|------|----------|
| 200 | 成功 | - |
| 400 | 请求参数错误 | 参数格式不正确、缺少必填参数 |
| 401 | 未授权 | 缺少认证信息或API Key无效 |
| 404 | 资源不存在 | 币种不存在或未被追踪 |
| 429 | 请求过于频繁 | 超过限流阈值（30次/秒） |
| 500 | 服务器内部错误 | 服务端异常 |
**错误响应示例**
```json
{
"success": false,
"error": "unauthorized"
}
```
---
## 使用示例
### cURL 示例
```bash
# 方式1: Query参数认证
curl "https://nofxos.ai/api/ai500/list?auth=your_api_key"
# 方式2: Header认证
curl "https://nofxos.ai/api/ai500/list" \
-H "Authorization: Bearer your_api_key"
# 获取1小时涨跌幅榜
curl "https://nofxos.ai/api/price/ranking?duration=1h&limit=20&auth=your_api_key"
# 获取多个时间周期涨跌幅榜
curl "https://nofxos.ai/api/price/ranking?duration=1h,4h,24h&limit=10&auth=your_api_key"
# 获取BTC详细数据
curl "https://nofxos.ai/api/coin/BTC?auth=your_api_key"
# 只获取BTC的资金流和OI数据
curl "https://nofxos.ai/api/coin/BTC?include=netflow,oi&auth=your_api_key"
# 获取4小时OI增加排行Top50
curl "https://nofxos.ai/api/oi/top-ranking?duration=4h&limit=50&auth=your_api_key"
# 获取24小时OI减少排行Top30
curl "https://nofxos.ai/api/oi/low-ranking?duration=24h&limit=30&auth=your_api_key"
# 获取机构合约资金流入排行
curl "https://nofxos.ai/api/netflow/top-ranking?type=institution&trade=future&duration=1h&auth=your_api_key"
# 获取散户现货资金流出排行
curl "https://nofxos.ai/api/netflow/low-ranking?type=personal&trade=spot&duration=4h&auth=your_api_key"
```
### Python 示例
```python
import requests
BASE_URL = "https://nofxos.ai"
API_KEY = "your_api_key"
# 方式1: Query参数认证
def get_with_query_auth(endpoint, params=None):
if params is None:
params = {}
params["auth"] = API_KEY
response = requests.get(f"{BASE_URL}{endpoint}", params=params)
return response.json()
# 方式2: Header认证
def get_with_header_auth(endpoint, params=None):
headers = {"Authorization": f"Bearer {API_KEY}"}
response = requests.get(f"{BASE_URL}{endpoint}", params=params, headers=headers)
return response.json()
# 获取AI500列表
def get_ai500_list():
return get_with_query_auth("/api/ai500/list")
# 获取涨跌幅榜
def get_price_ranking(durations="1h,4h,24h", limit=20):
return get_with_query_auth("/api/price/ranking", {
"duration": durations,
"limit": limit
})
# 获取币种详情
def get_coin_stats(symbol, include="netflow,oi,price,ai500"):
return get_with_query_auth(f"/api/coin/{symbol}", {
"include": include
})
# 获取OI排行
def get_oi_ranking(rank_type="top", duration="1h", limit=20):
endpoint = f"/api/oi/{rank_type}-ranking"
return get_with_query_auth(endpoint, {
"duration": duration,
"limit": limit
})
# 获取资金流排行
def get_netflow_ranking(rank_type="top", duration="1h", limit=20,
flow_type="institution", trade="future"):
endpoint = f"/api/netflow/{rank_type}-ranking"
return get_with_query_auth(endpoint, {
"duration": duration,
"limit": limit,
"type": flow_type,
"trade": trade
})
# 使用示例
if __name__ == "__main__":
# 获取AI500推荐币种
ai500 = get_ai500_list()
print(f"AI500推荐币种数量: {ai500['data']['count']}")
# 获取1小时涨幅榜前10
ranking = get_price_ranking("1h", 10)
for coin in ranking['data']['data']['1h']['top'][:3]:
# 注意: price_delta 是小数，需要×100
pct = coin['price_delta'] * 100
print(f"{coin['symbol']}: {pct:.2f}%")
# 获取BTC详情
btc = get_coin_stats("BTC")
# 注意: price_change 是小数
print(f"BTC 1小时涨跌: {btc['data']['price_change']['1h'] * 100:.2f}%")
# 获取4小时OI增加Top20
oi = get_oi_ranking("top", "4h", 20)
for pos in oi['data']['positions'][:3]:
# 注意: oi_delta_percent 已×100
print(f"{pos['symbol']}: OI变化 {pos['oi_delta_percent']:.2f}%")
```
### JavaScript/TypeScript 示例
```typescript
const BASE_URL = "https://nofxos.ai";
const API_KEY = "your_api_key";
// 通用请求函数
async function apiRequest<T>(endpoint: string, params: Record<string, any> = {}): Promise<T> {
const url = new URL(`${BASE_URL}${endpoint}`);
params.auth = API_KEY;
Object.entries(params).forEach(([key, value]) => {
url.searchParams.append(key, String(value));
});
const response = await fetch(url.toString());
return response.json();
}
// 获取涨跌幅榜
interface PriceRankingItem {
pair: string;
symbol: string;
price_delta: number; // 小数格式，0.05 = 5%
price: number;
future_flow: number;
spot_flow: number;
}
async function getPriceRanking(durations = "1h", limit = 20) {
const data = await apiRequest<any>("/api/price/ranking", { duration: durations, limit });
return data;
}
// 使用示例
async function main() {
const ranking = await getPriceRanking("1h,4h", 10);
for (const coin of ranking.data.data["1h"].top) {
// 转换为百分比显示
const pctChange = (coin.price_delta * 100).toFixed(2);
console.log(`${coin.symbol}: ${pctChange}%`);
}
}
```
---
## 常见问题
### Q: 为什么有些百分比字段格式不同？
A: 这是历史原因造成的：
- **OI接口**的 `oi_delta_percent` 和 `price_delta_percent` 是**已乘100**的格式（5.0 = 5%）
- **涨跌幅榜和币种详情**的 `price_delta` / `price_change` 是**小数**格式（0.05 = 5%）
建议在前端显示时统一处理。
### Q: duration 参数支持哪些值？
A: 支持以下值：`1m`, `5m`, `15m`, `30m`, `1h`, `4h`, `8h`, `12h`, `24h`(或`1d`), `2d`, `3d`, `5d`, `7d`
### Q: 如何判断资金是流入还是流出？
A: `amount`、`future_flow`、`spot_flow` 等字段：
- **正数** = 资金流入
- **负数** = 资金流出
### Q: API缓存时间是多久？
A: 所有数据接口缓存15秒，相同请求在15秒内返回缓存数据。
### Q: 限流规则是什么？
A: 每个IP每秒最多30次请求，超过会返回 429 错误。

350
docs/api/coin_api.md
View File

@@ -1,350 +0,0 @@
# 币种综合数据接口文档
## 接口概述
该接口提供单个币种的综合数据查询，一次请求即可获取资金净流入、持仓变化、价格变化等多维度数据。
## 请求信息
### 接口地址
```
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. **资金流向解读**：机构与散户的资金流向通常呈相反趋势，可作为市场情绪判断依据

254
docs/api/oi_api.md
View File

@@ -1,254 +0,0 @@
# 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

2
docs/architecture/STRATEGY_MODULE.zh-CN.md
View File

@@ -112,7 +112,7 @@ func (e *StrategyEngine) getCoinPoolCoins(limit int) []CandidateCoin {
}
```
- **API:** `config.CoinSource.CoinPoolAPIURL` (默认: `http://nofxaios.com:30006/api/ai500/list`)
- **API:** `config.CoinSource.CoinPoolAPIURL` (默认: `https://nofxos.ai/api/ai500/list`)
- **用途:** 获取 AI 评分最高的 N 个币种
- **标签:** `["ai500"]`