统计数据接口简介

XBlade Studio 统计数据 API 文档 - 提供交易量、用户行为等数据查询服务。

概述

统计数据接口提供平台运营数据、交易统计、用户行为分析等数据查询服务。主要用于监控机器人运行状态、分析交易量、追踪资金流向等。

主要功能

📊 交易量统计: 按时间、交易对查询交易量
📈 分组统计: 支持按天、按小时分组
💰 手续费统计: 累计手续费收入
🔍 灵活查询: 多维度过滤和聚合
🔐 安全认证: API Key认证保护

API 端点

交易量统计 API

GET /api/v1/admin/stats/trade-volume

查询指定时间范围内的交易量数据，支持多维度统计和分组。

请求参数

参数	类型	必填	说明
`start_date`	string	否	开始日期 (YYYY-MM-DD)，默认今天
`end_date`	string	否	结束日期 (YYYY-MM-DD)，默认今天
`symbol`	string	否	交易对符号（如 BTCUSDT）
`group_by`	string	否	分组方式：`day` 或 `hour`

请求头

X-API-Key: your_api_key_here

响应结构

{
  "summary": {
    "total_volume_usd": "10000000.00",
    "trade_count": 50000,
    "total_fees": "7000.00"
  },
  "by_symbol": [
    {
      "symbol": "BTCUSDT",
      "volume_usd": "5000000.00",
      "trade_count": 25000,
      "fees": "3500.00"
    },
    {
      "symbol": "ETHUSDT",
      "volume_usd": "3000000.00",
      "trade_count": 15000,
      "fees": "2100.00"
    },
    {
      "symbol": "SOLUSDT",
      "volume_usd": "2000000.00",
      "trade_count": 10000,
      "fees": "1400.00"
    }
  ],
  "by_time": [
    {
      "time_period": "2026-01-06",
      "volume": "10000000.00",
      "trades": 50000,
      "fees": "7000.00"
    }
  ]
}

字段说明

summary（总体统计）：

字段	类型	说明
`total_volume_usd`	string	总交易量（美元计价）
`trade_count`	integer	总交易笔数
`total_fees`	string	总手续费（USDT）

by_symbol（按交易对统计）：

字段	类型	说明
`symbol`	string	交易对符号
`volume_usd`	string	该交易对的交易量
`trade_count`	integer	该交易对的交易笔数
`fees`	string	该交易对的手续费

by_time（按时间统计）：

字段	类型	说明
`time_period`	string	时间段（日期或小时）
`volume`	string	该时间段的交易量
`trades`	integer	该时间段的交易笔数
`fees`	string	该时间段的手续费

使用示例

cURL 示例

查询今天的交易量

curl -X GET "https://api.renance.xyz/api/v1/admin/stats/trade-volume" \
  -H "X-API-Key: jLaOQFpw7GfWSUjccDdeprgPuVz6Cev8SmJu1IDLaek="

查询时间范围

curl -X GET "https://api.renance.xyz/api/v1/admin/stats/trade-volume?start_date=2025-12-25&end_date=2025-12-30" \
  -H "X-API-Key: jLaOQFpw7GfWSUjccDdeprgPuVz6Cev8SmJu1IDLaek="

查询特定交易对

curl -X GET "https://api.renance.xyz/api/v1/admin/stats/trade-volume?symbol=BTCUSDT" \
  -H "X-API-Key: jLaOQFpw7GfWSUjccDdeprgPuVz6Cev8SmJu1IDLaek="

按天分组查询

curl -X GET "https://api.renance.xyz/api/v1/admin/stats/trade-volume?start_date=2025-12-01&end_date=2025-12-30&group_by=day" \
  -H "X-API-Key: jLaOQFpw7GfWSUjccDdeprgPuVz6Cev8SmJu1IDLaek="

Python 示例

基础查询

import requests

api_key = "jLaOQFpw7GfWSUjccDdeprgPuVz6Cev8SmJu1IDLaek="
headers = {'X-API-Key': api_key}

# 查询今天的交易量
response = requests.get(
    'https://api.renance.xyz/api/v1/admin/stats/trade-volume',
    headers=headers
)

data = response.json()
print(f"总交易量: ${data['summary']['total_volume_usd']}")
print(f"总交易笔数: {data['summary']['trade_count']}")

高级查询

import requests
from datetime import datetime, timedelta

api_key = "jLaOQFpw7GfWSUjccDdeprgPuVz6Cev8SmJu1IDLaek="
headers = {'X-API-Key': api_key}

# 查询最近7天，按天分组
end_date = datetime.now().strftime('%Y-%m-%d')
start_date = (datetime.now() - timedelta(days=6)).strftime('%Y-%m-%d')

response = requests.get(
    'https://api.renance.xyz/api/v1/admin/stats/trade-volume',
    headers=headers,
    params={
        'start_date': start_date,
        'end_date': end_date,
        'group_by': 'day'
    }
)

data = response.json()

# 打印每天的交易量
for item in data.get('by_time', []):
    print(f"{item['time_period']}: ${item['volume']}")

查询工具

query_volume.py 工具

为了方便查询，项目提供了专用的查询工具 tools/query_volume.py。

快捷查询命令

# 查询今天的交易量
python3 tools/query_volume.py --today

# 查询昨天的交易量
python3 tools/query_volume.py --yesterday

# 查询最近7天的交易量（按天分组）
python3 tools/query_volume.py --last-7days

# 查询最近30天的交易量（按天分组）
python3 tools/query_volume.py --last-30days

自定义查询

# 查询特定日期范围
python3 tools/query_volume.py --start 2025-12-25 --end 2025-12-30

# 查询特定交易对
python3 tools/query_volume.py --today --symbol BTCUSDT

# 按天分组查询
python3 tools/query_volume.py --start 2025-12-01 --end 2025-12-30 --group-by day

# 按小时分组查询
python3 tools/query_volume.py --today --group-by hour

# 调试模式（查看原始API返回数据）
python3 tools/query_volume.py --today --debug

查询结果示例

================================================================================
📊 交易量统计结果
================================================================================

📈 总体统计:
--------------------------------------------------------------------------------
指标           | 数值         
-------------+------------
总交易量 (USDT)  | $10,000,000.00
总交易笔数        | 50,000      
总手续费 (USDT)  | $7,000.00    
平均交易额 (USDT) | $200.00    

💹 按交易对统计:
--------------------------------------------------------------------------------
交易对     | 交易量         | 笔数   | 手续费   
--------+-------------+------+-------
BTCUSDT | $5,000,000.00 | 25,000 | $3,500.00
ETHUSDT | $3,000,000.00 | 15,000 | $2,100.00
SOLUSDT | $2,000,000.00 | 10,000 | $1,400.00

================================================================================

工具特性

✅ 美化的表格输出: 清晰的对齐和分隔符
✅ 快捷查询命令: 今天/昨天/最近7天/30天
✅ 自定义日期范围: 灵活指定开始和结束日期
✅ 按交易对过滤: 查询特定交易对的数据
✅ 按时间分组: 支持按天或按小时分组
✅ 调试模式: --debug 查看原始API返回
✅ 无需外部依赖: 仅需Python标准库 + requests

使用场景

场景1：监控今日交易量是否达标

# 快速查询今天的总交易量
python3 tools/query_volume.py --today

# 预期：查看是否接近10M-15M目标

用途：

实时监控机器人运行效果
判断是否需要调整参数
确认是否达到日交易量目标

场景2：对比不同交易对的活跃度

# 查询今天数据，查看哪个交易对最活跃
python3 tools/query_volume.py --today

# 查看by_symbol部分的交易笔数

用途：

分析交易对权重配置是否合理
识别热门交易对
优化资源分配

场景3：分析最近一周的趋势

# 按天分组查看最近7天的数据
python3 tools/query_volume.py --last-7days

# 观察每天的交易量变化趋势

用途：

识别交易量趋势
发现异常波动
评估策略效果

场景4：查询特定交易对的表现

# 只查看BTCUSDT的数据
python3 tools/query_volume.py --today --symbol BTCUSDT

# 分析该交易对的交易量和手续费

用途：

深入分析单个交易对
对比不同交易对表现
优化交易对配置

场景5：调试API返回问题

# 使用debug模式查看完整的API响应
python3 tools/query_volume.py --today --debug

# 查看原始JSON数据结构

用途：

排查API问题
验证数据格式
开发调试

机器人集成

刷量机器人中的使用

刷量机器人内置了交易量监控功能：

def monitor_volume(self):
    """监控总交易量，达到限额自动停止"""
    while self.running:
        today = datetime.now().strftime('%Y-%m-%d')
        url = "https://api.renance.xyz/api/v1/admin/stats/trade-volume"
        params = {'start_date': today, 'end_date': today}
        headers = {'X-API-Key': self.api_key}
        
        response = requests.get(url, params=params, headers=headers, timeout=10)
        if response.status_code == 200:
            data = response.json()
            total_volume = float(data['summary']['total_volume_usd'])
            
            if total_volume >= 15000000:  # 15M限额
                logger.warning("今日交易量已达标，停止机器人")
                self.running = False
                break
            else:
                logger.info(f"当前今日交易量: ${total_volume:,.2f} / $15,000,000")
        
        time.sleep(60)  # 每分钟检查一次

功能：

每分钟自动查询当日交易量
达到15M限额自动停止机器人
实时显示交易量进度

性能分析

根据查询结果分析性能

# 查询今天的数据
python3 tools/query_volume.py --today

# 示例输出分析
总交易量: $10,000,000.00
总交易笔数: 50,000
运行时长: 假设运行了12小时

# 计算指标
每小时交易量 = $10,000,000 / 12 = $833,333
每分钟交易笔数 = 50,000 / (12 × 60) = 69笔
平均单笔金额 = $10,000,000 / 50,000 = $200

优化建议：

指标	当前值	目标值	建议
日交易量	$10M	$15M	增加交易频率或金额
每分钟笔数	69笔	90-120笔	增加活跃账户数量
平均单笔	$200	$180-220	当前合理
交易对分布	BTC 50%, ETH 30%, SOL 20%	BTC 57%, ETH 29%, SOL 14%	调整权重配置

数据更新频率

数据类型	更新频率	说明
实时交易数据	即时	每笔交易立即记录
统计聚合	每分钟	后台定期聚合计算
历史数据	每日归档	凌晨归档前一天数据

限流说明

每个 API Key 限制: 100 请求/分钟
超出限制: 返回 429 状态码
建议: 使用查询工具的快捷命令，避免频繁请求

错误处理

常见错误码

状态码	说明	解决方法
401	未授权	检查 X-API-Key 是否正确
400	参数错误	检查日期格式和参数值
429	请求过多	降低请求频率
500	服务器错误	稍后重试或联系技术支持

Python 错误处理示例

import requests

try:
    response = requests.get(
        'https://api.renance.xyz/api/v1/admin/stats/trade-volume',
        headers={'X-API-Key': api_key},
        timeout=10
    )
    response.raise_for_status()  # 抛出HTTP错误
    
    data = response.json()
    # 处理数据
    
except requests.exceptions.HTTPError as e:
    if e.response.status_code == 401:
        print("API Key 无效")
    elif e.response.status_code == 429:
        print("请求过于频繁，请稍后重试")
    else:
        print(f"HTTP错误: {e}")
        
except requests.exceptions.Timeout:
    print("请求超时")
    
except requests.exceptions.RequestException as e:
    print(f"请求失败: {e}")

最佳实践

1. 合理使用查询工具

# ✅ 推荐：使用快捷命令
python3 tools/query_volume.py --today

# ❌ 不推荐：频繁调用API
while true; do curl ...; sleep 1; done

2. 缓存查询结果

import time

# 缓存查询结果，避免重复请求
cache = {}
cache_ttl = 60  # 缓存60秒

def get_volume_cached(date):
    if date in cache and time.time() - cache[date]['time'] < cache_ttl:
        return cache[date]['data']
    
    # 查询API
    data = query_api(date)
    cache[date] = {'data': data, 'time': time.time()}
    return data

3. 批量查询

# ✅ 推荐：一次查询多天数据
python3 tools/query_volume.py --last-7days

# ❌ 不推荐：循环查询每一天
for date in dates; do
    python3 tools/query_volume.py --start $date --end $date
done

4. 异常处理

# 始终添加异常处理
try:
    data = query_volume()
    process_data(data)
except Exception as e:
    logger.error(f"查询失败: {e}")
    # 使用默认值或重试

安全注意事项

⚠️ 重要提示：

API Key 保护:
- 不要在代码中硬编码 API Key
- 使用环境变量或配置文件
- 定期轮换 API Key
访问控制:
- API Key 仅供内部使用
- 不要分享给外部人员
- 记录 API 访问日志
数据安全:
- 统计数据仅供内部分析
- 不要公开交易量数据
- 遵守数据保密协议

概述​

主要功能​

API 端点​

交易量统计 API​

请求参数​

请求头​

响应结构​

字段说明​

使用示例​

cURL 示例​

查询今天的交易量​

查询时间范围​

查询特定交易对​

按天分组查询​

Python 示例​

基础查询​

高级查询​

查询工具​

query_volume.py 工具​

快捷查询命令​

自定义查询​

查询结果示例​

工具特性​

使用场景​

场景1：监控今日交易量是否达标​

场景2：对比不同交易对的活跃度​

场景3：分析最近一周的趋势​

场景4：查询特定交易对的表现​

场景5：调试API返回问题​

机器人集成​

刷量机器人中的使用​

性能分析​

根据查询结果分析性能​

数据更新频率​

限流说明​

错误处理​

常见错误码​

Python 错误处理示例​

最佳实践​

1. 合理使用查询工具​

2. 缓存查询结果​

3. 批量查询​

4. 异常处理​

安全注意事项​

相关文档​

概述