Exchange Currency

Interface Description

• Path: /client/member/exchange-currency
• Method: POST
• Description: Allow members to manually exchange their balance from one currency to another. The exchange rate is based on the system's currency rates.

Request Parameters

Parameter	Type	Required	Description
fromCurrency	String	Yes	Original currency code (e.g. USD)
toCurrency	String	Yes	Target currency code (e.g. CNY)
amount	Number	Yes	The amount of the original currency to exchange

Request Example

POST /client/member/exchange-currency

{
  "fromCurrency": "USD",
  "toCurrency": "CNY",
  "amount": 100
}

Response Parameters

Parameter	Type	Description
code	Number	Status code, 0 means success
msg	String	Message
data	Object	Exchange result
data.exchangedAmount	Number	The final obtained amount of the target currency
data.rate	Number	The applied exchange rate

Response Example

{
  "code": 0,
  "msg": "兑换成功",
  "data": {
    "exchangedAmount": 720,
    "rate": 7.2
  }
}

Common Error Codes and Messages

When code != 0, it means the request has failed. Below are the common msg prompts and their causes:

Error msg	Cause Analysis
parameter_error	Missing required parameters, amount format is incorrect (must be a number), or the submitted data format is unsupported (JSON and Form-Data are supported).
Failed: FromCurrency or ToCurrency must be the base currency	The exchange must involve the system's "Base Currency". Direct cross-exchange between two non-base currencies is not allowed.
Failed: The exchange amount exceeds the wallet balance	The user's wallet balance for the original currency (fromCurrency) is insufficient to cover the exchange amount.
verify_failed: unauthorized or verify_failed: invalid base token	No valid credentials provided. Please ensure that the Authorization: Bearer <Your_Member_Token> header is correctly included in the request.
Failed: cannot_convert_same_currency	fromCurrency and toCurrency are identical. Exchanging the same currency is not allowed.
Failed: amount_must_be_positive	The submitted amount must be greater than 0.
Failed: rate_not_found_for_xxx	The system could not find the exchange rate configuration for the specified currency. An unsupported currency code may have been entered.