单一钱包

在单一钱包（SEAMLESS）模式下，玩家余额保存在商户钱包中。玩家下注、中奖或退款时，平台会实时调用商户实现的接口来扣款或加款。

接口一览

方向	接口	说明
商户 → 平台	POST /v1/players	创建或取得玩家
商户 → 平台	POST /v1/launches	请求进入游戏
商户 → 平台	GET /v1/wallets、GET /v1/transactions/{id}	查询余额观察值和平台侧交易
平台 → 商户	GET /v1/wallets/balance	获取玩家余额
平台 → 商户	POST /v1/wallet-transactions	改变玩家余额（下注、派奖、退款、奖励）
平台 → 商户	GET /v1/wallet-transactions/{transaction_id}	查询交易状态，必须实现
平台 → 商户	POST /v1/round-events	对局结束通知

回调地址为 {MERCHANT_URL} 加上表中的固定路径，例如 https://wallet.example.com/v1/wallet-transactions。玩家级别的 URL 不支持。

回调通用要求

• 验签：钱包回调使用交付的 secret 签名，算法与商户调用平台相同，见回调签名。
• 定位玩家：用 external_player_id 定位玩家，也就是商户在创建玩家时传入的 ID。不要按昵称定位。
• 校验归属：每次都要校验玩家、币种是否属于当前商户。
• 响应格式：响应必须是 application/json，格式为 {"data":{...},"request_id":"..."}。data 中只能有文档列出的字段。
• 不能重定向：平台不会跟随 3xx 重定向。回调地址必须使用公网 HTTPS，并配有有效证书。

商户钱包必须保证

永久幂等

每一笔资金请求都有平台生成的 transaction_id，对应请求头 Idempotency-Key。商户必须按 (商户, transaction_id) 永久去重：

• 同一个 transaction_id 再次到达时，返回首次结果（包括当时的余额），并带响应头 Idempotency-Replayed: true。不要再扣一次或加一次。
• 同一个 transaction_id 但内容不同，返回 409 IDEMPOTENCY_CONFLICT。
• 余额变化、交易记录和终态必须在同一个事务中提交。

• 能查单：任何收到过的 transaction_id，都能通过查询交易状态查到当前结果。查单要读取权威记录，不能读缓存或报表。
• 终态不可逆：SUCCEEDED 和 FAILED 一旦返回，就不能再改变。
• 结果不明时返回 UNKNOWN：商户自己也无法确认结果时，返回 UNKNOWN，平台会稍后查单，不要猜测结果。

平台开通单一钱包新业务前，会自动核验以上能力。见单一钱包回调核验。

平台的重试与恢复

平台发出资金请求之前，就会把 transaction_id 固定下来。遇到下面这些情况，平台都不会认为交易失败：

• 超时或连接断开
• HTTP 5xx、401 或 429
• 响应结构不完整
• 响应中的 ID、金额或币种与请求不一致
• 状态为 UNKNOWN
• 返回了错误信封（error）

平台会用同一个 transaction_id 查单或重发，间隔依次约为 1 秒、5 秒、30 秒、2 分钟、10 分钟、30 分钟，之后每小时一次，并遵守 Retry-After。平台不会换新 ID。

查单返回 404 TRANSACTION_NOT_FOUND 时，原请求可能还在路上。平台会继续按同一个 ID 恢复。

资金类型

kind	方向	说明
BET	扣款	下注，带 round_id
PAYOUT	加款	派奖，带 round_id 和 allocations。输局不发零金额派奖
REFUND	加款	退还一笔已成功的 BET，带 reference_transaction_id 和原 round_id。可以全额或部分退款
GIFT	加款	已授权的活动现金奖励，不关联下注

amount 始终大于 0，方向由 kind 决定。