nofx/docs/api/API_REFERENCE.md

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

响应格式

成功响应：

{
  "success": true,
  "data": { ... }
}

错误响应：

{
  "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不能全为负）

响应示例

{
  "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

响应示例

{
  "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

响应示例

{
  "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

响应示例

{
  "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增加排行榜

示例

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

响应示例

{
  "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

查询参数 同 资金流入排行榜

示例

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

响应示例

{
  "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

响应示例

{
  "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	服务器内部错误	服务端异常

错误响应示例

{
  "success": false,
  "error": "unauthorized"
}

---

使用示例

cURL 示例

# 方式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 示例

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 示例

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 错误。