2.5 Wallet Transfer (Deposit / Withdraw)

POST /api/v1/user/exchange/wallets/{external_player_id}/deposits
POST /api/v1/user/exchange/wallets/{external_player_id}/withdrawals

• deposits: wallet deposit
• withdrawals: wallet withdraw

Request Body (JSON)

Field	Required	Type	Description
currency	TRUE	string	Must match the currency bound to the agent; see Supported Currencies
amount	TRUE	string	Amount change, represented as a string; per-transaction cap 10,000,000, up to 8 decimal places
ticket_id	TRUE	string	Idempotency key, a unique string, up to 256 characters; the same ticket_id will not take effect twice

{
  "currency": "CNY",
  "amount": "10",
  "ticket_id": "3e2178ba-269c-4649-2fdb-a2099d6479a6"
}

TIP

ticket_id is the idempotency key: when a request is repeated with the same ticket_id, the system returns the original response from the first successful call (including the balance at that time) and does not post the entry again. That balance is a snapshot from the initial processing and does not reflect the current balance; for the latest balance, call the Balance Query API.

A player being in-game does not affect transfer operations; deposits / withdrawals can be initiated normally.

Response data

Field	Type	Description
wallet.currency	string	Currency
wallet.balance	string	Balance snapshot after this transaction is processed
created_at	string	Initial processing time (RFC 3339, nanosecond precision)

{
  "code": 0,
  "message": "success",
  "data": {
    "wallet": {
      "currency": "CNY",
      "balance": "251080.82"
    },
    "created_at": "2026-06-18T05:00:02.962216637Z"
  }
}

Transaction Failures and Refund Handling

IMPORTANT

Before issuing a refund or reprocessing, you must first call the Transaction Status Query API to confirm the final status of the original transaction, to avoid duplicate refunds or refunding a transaction that was never actually charged.

On timeout, network error, or an ambiguous response, do not issue a refund directly. The correct procedure:

1. Call the transaction status query API with the original ticket_id to confirm whether the transaction was successfully posted.
2. After confirming it was not successful, issue the refund (deposit) with a new ticket_id.
3. If confirmed successful, no action is needed, or initiate a separate refund flow according to your business requirements.