开发指南
充值查询与对账
补查任务和原单/收件箱在同一持久事务创建，以作用域 + 原单或 txRef 去重。worker 使用有期限的领取租约，崩溃后可重领，完成更新必须核对持有者/租约版本；退避有上限，超出自动重试预算转有负责人的持久人工核查。未知结果不删除任务、不换单号；通知先到、查询先到和重启重投共用同一账务事务。对已确认充值持续复核，以发现失效和恢复。
充值与提现列表使用不同参数。操作：先按下表选择接口，再把最终 query 原始字节放入 HMAC；不要给所有列表套一套分页参数。
| 接口 | 范围 | 排序与数量 |
|---|---|---|
玩家充值：GET /v1/players/{playerId}/deposits?chainId=... | 当前同步的三种充值状态，不按 24 小时截断；唯一 query 是 chainId | 首次发现顺序倒序，同一 txRef 一条，最多 1000 条，无下一页 |
玩家提现：GET /v1/players/{playerId}/withdrawals?chainId=...&page=1&pageSize=20 | 当前 HMAC 接入方、原玩家、当前允许读取完整链事实的已受理订单 | acceptedAt 秒倒序，同秒按 30 位 withdrawOrderId 字节倒序；响应 {items,total,page,pageSize} |
提现 page 默认 1，只接受无前导零的正十进制字符串，最大 10001；pageSize 默认 20，仅可填 20 或 50。同时要求 (page - 1) * pageSize <= 200000。三个 query 名各至多一次，GET body 为空，不支持 cursor、时间或地址筛选。列表项与单笔提现查询相同，不另带 playerId、管理侧标识或 scope；status 仍可能是 held。OG 使用自己保存的原订单关联玩家。
这是 offset 分页。新单在翻页期间出现时，边界会移动；按 withdrawOrderId 合并去重并定期刷新首页，不把一次翻页看作冻结快照，也不承诺无限历史回补。acceptedAt 是首次受理时间，不是链上提现完成时间。充值响应没有精确链上时间，区块/log 排序只用于同一网络的展示；不要用通知接收时间或账本刷新时间补造。
预期：无匹配或提现超出末页都返回 HTTP 200 和空 items。空列表、503 或没有某笔未知提现都不释放 OG 预扣；仍按原订单单笔核查。失败首查 401 的原始签名 query、422 的参数/分页边界、503 的依赖与原单完整性，然后核对玩家和完整环境/网络范围。
高级对账兼容入口
近 24 小时充值对账（GET /v1/deposits）保留给既有补偿任务；只是默认 API 导航收起，不删除、不弃用。它不带 query/body、无分页/排序保证，只返回服务记录确认时间在近 24 小时且当前仍为 confirmed 的记录，项目不带 status。
窗口或玩家列表缺失记录不证明失效，必须按已知 txRef 单笔复核。中断接近/超过 24 小时、玩家充值达到 1000 条或提现页数/offset 达到边界时，记录覆盖缺口并请求平台历史核查；OG 自有完整账本不可被空列表覆盖。预期高级补偿和旧直链继续可用；失败先查范围及同步覆盖，不清账或重新转账验证。