账户余额

账户余额 API 用于查询商户账户维度的币种余额，支持按单一币种查询明细，也支持按展示币种汇总所有币种余额。

接入准备

调用账户服务前，请先完成 账户服务接入准备。

余额查询

余额查询 API 返回指定币种的账户余额明细。

POST

请求参数

Parameter	Type	Length	Required	Signed	Description
requestId	String	/	Yes	No	Unique request ID for idempotency and request tracing.
requestTime	Long	/	Yes	No	Request timestamp in milliseconds. The timestamp must be within 10 minutes of the server time.
currency	String	/	Yes	No	Currency code, for example USD or EUR.

响应

Name	Type	Description
code	String	Response code.
message	String	Response message.
data	Object	Balance details.
└currency	String	Currency code.
└withdrawableBalance	String	Withdrawable balance.
└availableBalance	String	Available balance.
└fundOnHold	String	Funds that are on hold or in transit.
└depositBalance	String	Deposit balance.
└totalBalance	String	Total balance, including available, on-hold, and deposit amounts.
└status	String	Account status.

API 使用示例

请求

{
  "requestId": "REQ-BAL-20260423-0001",
  "requestTime": 1776931200000,
  "currency": "USD"
}

响应

{
  "code": "200",
  "message": "success",
  "data": {
    "currency": "USD",
    "withdrawableBalance": "1000.00",
    "availableBalance": "1500.00",
    "fundOnHold": "300.00",
    "depositBalance": "200.00",
    "totalBalance": "2000.00",
    "status": "ACTIVE"
  }
}

余额总览查询

余额总览查询 API 返回所有币种的余额汇总，并可按 displayCurrency 展示换算后的总金额。

POST

请求参数

Parameter	Type	Length	Required	Signed	Description
requestId	String	/	Yes	No	Unique request ID for idempotency and request tracing.
requestTime	Long	/	Yes	No	Request timestamp in milliseconds. The timestamp must be within 10 minutes of the server time.
displayCurrency	String	/	No	No	Display currency used for amount conversion. Defaults to USD when omitted.

响应

Name	Type	Description
code	String	Response code.
message	String	Response message.
data	Object	Balance overview.
└totalAmount	String	Total amount converted to the display currency.
└displayCurrency	String	Display currency. Defaults to USD.
└currencyBalances	Array	Balance summary by currency.
└currency	String	Currency code.
└withdrawableBalance	String	Withdrawable balance.
└availableBalance	String	Available balance.
└fundOnHold	String	Funds that are on hold or in transit.
└depositBalance	String	Deposit balance.
└totalBalance	String	Total balance, including available, on-hold, and deposit amounts.
└status	String	Account status.

API 使用示例

请求

{
  "requestId": "REQ-BAL-20260423-0002",
  "requestTime": 1776931200000,
  "displayCurrency": "USD"
}

响应

{
  "code": "200",
  "message": "success",
  "data": {
    "totalAmount": "5000.00",
    "displayCurrency": "USD",
    "currencyBalances": [
      {
        "currency": "USD",
        "withdrawableBalance": "1000.00",
        "availableBalance": "1500.00",
        "fundOnHold": "300.00",
        "depositBalance": "200.00",
        "totalBalance": "2000.00",
        "status": "ACTIVE"
      },
      {
        "currency": "EUR",
        "withdrawableBalance": "2000.00",
        "availableBalance": "2500.00",
        "fundOnHold": "500.00",
        "depositBalance": "0.00",
        "totalBalance": "3000.00",
        "status": "ACTIVE"
      }
    ]
  }
}

实施建议

1. 为每次请求生成唯一 requestId，方便排查链路和避免重复处理。
2. 使用毫秒级 requestTime，并确保调用方服务器时间与标准时间保持同步。
3. 将余额数据与账户流水定期对账，避免只依赖单次余额快照。