3.2 Wallet Transfer Records API

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

Query transfer wallet transaction records (bet deductions, payouts, refunds, deposits, withdrawals, etc.) by time range with pagination. Data comes from the historical store and may lag by a few seconds; the most recent 6 months are retained. Requests must include the HMAC authentication headers.

TIP

This API is rate-limited to 100 requests / minute; exceeding it returns code:10060. The quota is counted per api_key × endpoint — endpoints do not share a quota, and every request (including those returning an error) counts toward it.

Request Parameters (Query String)

Field	Required	Type	Description
start_time	TRUE	string	Start time (≥), RFC3339 UTC, e.g. 2026-05-19T00:00:00Z
end_time	TRUE	string	End time (≤), RFC3339 UTC, must be later than start_time; the span cannot exceed 90 days
source_id	FALSE	string	Source ID (ticket / reference number)
order_id	FALSE	string	Search for records containing this exchange order ID
player_id	FALSE	string	Internal player ID (UUID)
player_name	FALSE	string	Player name
transaction_type	FALSE	string	Transaction type (see enum below)
page / page_size	FALSE	integer	Pagination; page starts at 1, default 1; page_size defaults to 10, max 200, values ≤0 or >200 fall back to 10

The agent dimension is locked automatically by the system based on api_key; it cannot and need not be specified via parameters.

Response data

data contains items[] (transaction records) and pagination fields (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[] fields

Field	Type	Description
id	string	Unique ID of this wallet record (UUID)
player_id	string	Internal player ID (UUID)
player_external_id	string	Player ID
player_name	string	Player name
agent_id	string	Internal agent ID (UUID)
agent_name	string	Agent name
transaction_type	string	Transaction type (enum, see below)
kind	string	Record kind
source_id	string	Source ID; for deposits / withdrawals this is the ticket_id sent in the request, for bet-related records the corresponding source reference
source_id_type	string	Type of the source_id source
order_ids	array	Exchange order IDs linked to this record; may contain more than one — see below
currency	string	Currency
amount	string	Amount change (may be negative, e.g. bet deduction)
balance_after	string	Balance after this change
created_at	string	Transaction time (RFC3339 UTC)

order_ids Behavior

order_ids lists the exchange orders linked to this wallet record and may contain more than one entry: payouts are aggregated by "player × event × market", so a single SETTLEMENT_PAYOUT can cover several bets (up to 6 observed in production).

transaction_type	order_ids count
DEPOSIT, WITHDRAW	Empty array (not bet-related)
BET_DEDUCT, HEDGE_REFUND, MTS_REJECT_REFUND, PLAYER_CANCEL_REFUND	Always 1
SETTLEMENT_PAYOUT, ROLLBACK_CLAWBACK	May be several

IMPORTANT

The amount of an aggregated record cannot be broken back down to individual bets through this API. For per-bet amounts, use trades[] from the Bet Ticket Query API.

Incremental Reconciliation

created_at is the time the platform wrote the ledger entry. It increases monotonically and works well as a cursor for incremental pulls.

IMPORTANT

This API covers only events where money actually moved. A losing bet produces no wallet record at all — the funds were deducted when the bet was placed, and settlement moves nothing further. Payouts and rollback clawbacks are likewise written only when the amount is greater than 0.

Recommended reconciliation split:

• Cash flow: pull incrementally from this API by created_at.
• Bet status and P&L: use the Bet Ticket Query API with an order time range or settlement time range.

Enums

Transaction type transaction_type (prefix EXCHANGE_TRANSACTION_TYPE_)

Value	Description
BET_DEDUCT	Bet deduction
SETTLEMENT_PAYOUT	Settlement payout
ROLLBACK_CLAWBACK	Settlement rollback clawback
PLAYER_CANCEL_REFUND	Player cancellation refund
HEDGE_REFUND	Hedge refund
BET_CANCEL_REFUND	Bet void refund
MTS_REJECT_REFUND	MTS rejection refund
ADMIN_CANCEL_REFUND	Back-office cancellation refund
ADMIN_CANCEL_CLAWBACK	Back-office cancellation clawback
DEPOSIT	Deposit
WITHDRAW	Withdrawal
RE_SETTLEMENT_PAYOUT	Reserved value; no write path exists today, it will not appear
MARKET_SUSPEND_REFUND	Reserved value; no write path exists today, it will not appear

TIP

A re-settlement actually produces two records — ROLLBACK_CLAWBACK and SETTLEMENT_PAYOUT. It never produces RE_SETTLEMENT_PAYOUT.