3.4 汇总统计 API

GET /api/v1/exchange/report/trade-summary

查询当前代理在指定时间范围内、所有玩家的 exchange trade 汇总统计（含有效、不成立、未结算三个分类）。数据可能有数秒同步延迟，保留最近 6 个月数据。请求须带入 HMAC 验证 Header。

TIP

本 API 限流 100 次 / 分钟（per api_key），超过返回 code:10060。

代理维度由系统依据 api_key 自动锁定，无需也无法通过参数指定。

请求参数（Query String）

提供两组可选时间范围，格式均为 RFC3339 UTC：

字段	类型	说明
create_start_time	string	撮合（提交）时间起（≥），RFC3339 UTC
create_end_time	string	撮合时间迄（<），RFC3339 UTC
settlement_start_time	string	结算时间起（≥），RFC3339 UTC
settlement_end_time	string	结算时间迄（<），RFC3339 UTC

TIP

• 至少提供一组（create 或 settlement）；两组同时提供时为 AND 条件（撮合落在 A 区间且结算落在 B 区间）。
• 每组必须同时给 start 与 end，缺其一返回 code:10020。
• 每组区间最长 90 天，超过返回 code:10020；最小区间可支持 1 秒。
• 未结算（pending）的 trade 无结算时间，仅在 create 区间被纳入；只提供 settlement 区间时不会出现未结算统计。

示例

GET /api/v1/exchange/report/trade-summary?create_start_time=2026-05-19T00:00:00Z&create_end_time=2026-06-18T00:00:00Z

响应 data

{
  "code": 0,
  "message": "success",
  "data": {
    "trade_count": 9,
    "win_count": 2,
    "lose_count": 0,
    "void_count": 0,
    "unsettled_count": 7,
    "currency": "EUR",
    "total_turnover": "701.00000000",
    "valid_turnover": "374.00000000",
    "void_turnover": "0.00000000",
    "unsettled_turnover": "327.00000000",
    "commission": "8.11750000",
    "net_pnl": "154.23250000",
    "total_payout": "528.23250000",
    "usd_total_turnover": "771.10000000",
    "usd_valid_turnover": "411.40000000",
    "usd_void_turnover": "0.00000000",
    "usd_unsettled_turnover": "359.70000000",
    "usd_commission": "8.92900000",
    "usd_net_pnl": "169.65500000"
  }
}

响应字段

字段	类型	说明
trade_count	integer	总笔数（三个分类合计）；无数据时返回 0
win_count	integer	有效 — 赢的笔数（WIN / HALF_WIN）
lose_count	integer	有效 — 输的笔数（LOSE / HALF_LOSE）
void_count	integer	不成立的笔数
unsettled_count	integer	未结算的笔数
currency	string	该代理绑定币种；无数据时为空字符串
total_turnover	string	完整流水 = 有效 + 不成立 + 未结算，小数字符串固定 8 位
valid_turnover	string	有效流水，小数字符串固定 8 位
void_turnover	string	不成立流水，小数字符串固定 8 位
unsettled_turnover	string	未结算流水，小数字符串固定 8 位
commission	string	佣金（仅统计有效），小数字符串固定 8 位
net_pnl	string	盈亏（仅统计有效），玩家视角：正 = 玩家净赢，已扣佣金；net_pnl = total_payout − valid_turnover；可为负值
total_payout	string	派彩（仅统计有效），小数字符串固定 8 位
usd_total_turnover	string	完整流水（USD），小数字符串固定 8 位
usd_valid_turnover	string	有效流水（USD），小数字符串固定 8 位
usd_void_turnover	string	不成立流水（USD），小数字符串固定 8 位
usd_unsettled_turnover	string	未结算流水（USD），小数字符串固定 8 位
usd_commission	string	佣金（USD），小数字符串固定 8 位
usd_net_pnl	string	盈亏（USD），小数字符串固定 8 位；可为负值

分类定义

每笔提交依结算状态归入唯一一个分类，各字段的计数与流水均以此为基础汇总：

• 有效：settlement_status = SETTLED 且 settlement_result 为 WIN / HALF_WIN / LOSE / HALF_LOSE
• 不成立：SETTLED 但 PUSH / VOID，或 market-voided，或撮合被拒（rejected）
• 未结算：status = accepted 且 settlement_status = PENDING