获取玩家余额

由商户实现，平台调用

GET {MERCHANT_URL}/v1/wallets/balance，使用交付的 secret 签名。

平台在玩家进入游戏或需要展示余额时调用本接口。这个余额只用于展示，下注时的扣款以改变玩家余额的结果为准。

请求参数（query）

参数	必填	类型	说明
external_player_id	是	string	商户侧玩家 ID
currency	是	string	币种代码

query 参数按字母排序并做 URL 编码。验签时请使用收到的原始 query 字符串：

GET /v1/wallets/balance?currency=USD&external_player_id=merchant-user-1

成功响应 200

字段	类型	说明
balance	decimal string	当前可用余额，精度不能超过该币种的 decimal_scale
currency	string	必须与请求中的币种相同
as_of	string	余额的观察时间，UTC RFC3339

{
  "data": { "balance": "1250.50", "currency": "USD", "as_of": "2026-09-23T08:00:01Z" },
  "request_id": "b3f1c2d4-balance-0001"
}

失败响应

场景	HTTP	error.code
玩家在商户侧不存在	404	RESOURCE_NOT_FOUND
该玩家不支持这个币种	422	CURRENCY_NOT_SUPPORTED
暂时无法读取余额	503	DEPENDENCY_UNAVAILABLE

无法确认时不要返回 0

读取失败时返回错误，不要返回 "0"。平台在超时或收到异常响应时，会保留上一次的观察值，并且不会展示伪造的 0 余额。

签名示例

使用接入说明中的示例密钥 secret，签名 GET /v1/wallets/balance?currency=USD&external_player_id=merchant-user-1，没有幂等键和 body。请求头如下：

项	值
X-Merchant-Id	M123456789ABC
X-Timestamp	1790150400

期望签名：

X-Signature: 8cd09266cbde8789b023661c95b2c16707433a39c0db2682583daedf85e98b5d