feat: unify NofxOS data provider and fix language consistency

- 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
2026-07-07 13:00:59 +08:00 · 2026-01-04 00:59:07 +08:00
parent 13fda47151
commit 0275e23b7e
32 changed files with 3029 additions and 1767 deletions
--- a/docs/api/API_REFERENCE.md
+++ b/docs/api/API_REFERENCE.md
@@ -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 错误。