3.2 查转账钱包记录 API

GET /api/v1/exchange/report/transfer-wallet-transactions

按时间区间分页查询转账钱包交易流水（下注扣款、派彩、退款、存款、提款等）。数据来源为历史库，可能有数秒同步延迟，保留最近 6 个月数据。请求须带入 HMAC 验证 Header。

TIP

本 API 限流 100 次 / 分钟，超过返回 code:10060。额度按 api_key × 接口独立计算，各接口不共用；每次请求（含返回错误者）均计入。

请求参数（Query String）

字段	必填	类型	说明
start_time	TRUE	string	起始时间（≥），RFC3339 UTC，例如 2026-05-19T00:00:00Z
end_time	TRUE	string	结束时间（≤），RFC3339 UTC，须晚于 start_time，跨度不可超过 90 天
source_id	FALSE	string	来源 ID（ticket / 单号）
order_id	FALSE	string	搜索包含此交易所 order ID 的记录
player_id	FALSE	string	玩家内部 ID（UUID）
player_name	FALSE	string	玩家名称
transaction_type	FALSE	string	交易类型（见下方枚举）
page / page_size	FALSE	integer	分页，page 从 1 起，默认 1；page_size 默认 10，最大 200，传入 ≤0 或 >200 自动回退为 10

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

响应 data

data 包含 items[]（交易记录）及分页字段（total / page / page_size / total_pages）。

{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "id": "0f8c1b2a-6d4e-4a1f-9c33-2a1d4e6f7a80",
        "player_id": "45d3d8eb-1a95-4e47-9315-bc507ea06d65",
        "player_external_id": "player1",
        "player_name": "player1_name",
        "agent_id": "bea4274e-4333-423c-a8e8-4c203d256d2c",
        "agent_name": "agent_demo",
        "transaction_type": "EXCHANGE_TRANSACTION_TYPE_BET_DEDUCT",
        "kind": "",
        "source_id": "019e0000-0000-0000-0000-000000000000",
        "source_id_type": "",
        "order_ids": ["019e0000-0000-0000-0000-000000000000"],
        "currency": "CNY",
        "amount": "-100",
        "balance_after": "900",
        "created_at": "2026-05-20T10:00:00Z"
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 10,
    "total_pages": 1
  }
}

items[] 字段

字段	类型	说明
id	string	该笔钱包记录的唯一 ID（UUID）
player_id	string	玩家内部 ID（UUID）
player_external_id	string	玩家 ID
player_name	string	玩家名称
agent_id	string	代理内部 ID（UUID）
agent_name	string	代理名称
transaction_type	string	交易类型（枚举，见下方）
kind	string	记录类型
source_id	string	来源 ID；转入 / 转出为请求带入的 ticket_id，注单相关记录为对应的来源单号
source_id_type	string	source_id 的来源类型
order_ids	array	本笔记录关联的交易所挂单号；可为多笔，详见下方说明
currency	string	货币
amount	string	金额变动（可为负，如下注扣款）
balance_after	string	本次变动后余额
created_at	string	交易时间（RFC3339 UTC）

order_ids 行为

order_ids 为本笔钱包记录关联的挂单号列表，可为多笔：派彩以「玩家 × 赛事 × 盘口」聚合，一笔 SETTLEMENT_PAYOUT 可能同时对应多张注单（PROD 实测单笔最多 6 个）。

transaction_type	order_ids 笔数
DEPOSIT、WITHDRAW	空数组（与注单无关）
BET_DEDUCT、HEDGE_REFUND、MTS_REJECT_REFUND、PLAYER_CANCEL_REFUND	均为 1 笔
SETTLEMENT_PAYOUT、ROLLBACK_CLAWBACK	可能多笔

IMPORTANT

聚合记录的 amount 无法从本 API 拆回单张注单。需要单张注单的金额，请改用注单查询 API 的 trades[]。

增量对账

created_at 为平台写入账本的时间，单调递增，适合作为增量拉取的游标。

IMPORTANT

本 API 只涵盖资金实际发生变动的事件。结算结果为输的注单不会产生任何钱包记录——资金在下单时已扣除，结算不再动账。派彩与回滚扣回也仅在金额 > 0 时才写入记录。

对账建议：

• 资金流水：以本 API 依 created_at 增量拉取。
• 注单状态与盈亏：改用注单查询 API，搭配下单时间区间或结算时间区间查询。

枚举

交易类型 transaction_type（前缀 EXCHANGE_TRANSACTION_TYPE_）

值	说明
BET_DEDUCT	下注扣款
SETTLEMENT_PAYOUT	结算派彩
ROLLBACK_CLAWBACK	结算回滚扣回
PLAYER_CANCEL_REFUND	玩家取消退款
HEDGE_REFUND	对冲退款
BET_CANCEL_REFUND	注单作废退款
MTS_REJECT_REFUND	MTS 拒绝退款
ADMIN_CANCEL_REFUND	后台取消退款
ADMIN_CANCEL_CLAWBACK	后台取消扣回
DEPOSIT	存款
WITHDRAW	提款
RE_SETTLEMENT_PAYOUT	保留值，目前无写入路径，不会出现
MARKET_SUSPEND_REFUND	保留值，目前无写入路径，不会出现

TIP

重新结算实际只会产生 ROLLBACK_CLAWBACK 与 SETTLEMENT_PAYOUT 两笔记录，不会产生 RE_SETTLEMENT_PAYOUT。