查询钱包余额

创建玩家时不会创建钱包。玩家首次进入游戏或首次发生资金交易时，平台才按币种创建钱包；查询接口不会创建钱包，所以新玩家的列表可能为空。

钱包列表

GET {API_URL}/v1/wallets

参数	必填	类型	说明
player_id	否	string	只看某个玩家
currency	否	string	只看某个币种
offline_only	否	boolean	true 时只返回当前不在游戏中的玩家。仅转账钱包
nonzero_only	否	boolean	true 时只返回余额不为 0 的钱包，必须同时传 offline_only=true。仅转账钱包
limit	否	integer	每页条数，1–1000，默认 100
cursor	否	string	续页游标，来自上一页的 next_cursor

offline_only=true&nonzero_only=true 适合找出“已经离开游戏但平台里还有余额”的玩家，方便批量转出。单一钱包商户使用这两个参数时返回 422。

成功响应 200

字段	类型	说明
wallet_id	string	钱包 ID
player_id	string	平台玩家 ID
currency	string	币种代码
wallet_mode	string	TRANSFER 或 SEAMLESS
balance	decimal string | null	余额，见下表
balance_kind	string	LEDGER 或 OBSERVED
as_of	string | null	余额时间
online	boolean	玩家当前是否在游戏中

钱包模式	balance_kind	balance 的含义
转账钱包	LEDGER	平台账本余额，权威值
单一钱包	OBSERVED	平台最近一次从商户读到的余额，只作参考；从未读到时为 null

{
  "data": {
    "items": [
      {
        "wallet_id": "0192f6d2-4c5b-7e6f-9a01-7b8c9d0e1f2a",
        "player_id": "0192f6a4-3c1e-7b2a-9d40-5e8f1a2b3c4d",
        "currency": "USD",
        "wallet_mode": "TRANSFER",
        "balance": "86.50",
        "balance_kind": "LEDGER",
        "as_of": "2026-09-23T08:30:00Z",
        "online": false
      }
    ],
    "next_cursor": null,
    "has_more": false
  },
  "request_id": "0192f6d2-req-0001"
}

续页时带上 cursor。游标与首次请求的筛选条件绑定。

钱包详情

GET {API_URL}/v1/wallets/{wallet_id}

返回单个钱包的当前余额，字段同上（不含 online），balance 和 as_of 一定有值。

• 转账钱包：读取平台账本。
• 单一钱包：平台会实时调用商户的获取玩家余额接口。无法确认时返回 503 DEPENDENCY_UNAVAILABLE，不会用旧值或 0 代替。