开发指南
接入概览
需要 AI 生成接入工程时，从 AI 自包含接入包 开始。包内提供公开契约、配置模板、client/身份/账务/worker 适配接口和固定离线验收；先完成离线矩阵，再用真实配置核对环境。
通过这些接口，你的业务系统可以为玩家获取充值地址、查询充值与提现历史、提交提现、取消尚未广播的提现，并接收交易通知。接口使用 HTTPS 和 JSON，由你的业务后端调用；手机页面读取你们自己的持久账本和业务结果。
双方分别负责什么
| 支付平台 | 你的业务系统 |
|---|---|
| 提供充值地址、同步链上记录、受理提现并提供查询与通知 | 管理玩家、展示地址、换算金额，并记录每笔充值和提现的账务结果 |
| 提供交易状态 | 根据状态入账、确认扣款或释放预扣，防止重复处理，并定期对账 |
本文的账务术语含义如下：
| 术语 | 含义 |
|---|---|
| 入账 | 将已确认的充值计入玩家业务余额 |
| 预扣 | 提现前暂时占用玩家余额，防止同一余额被重复使用；此时尚未确认提现完成 |
| 释放预扣 | 解除先前占用，恢复可用余额；不是再额外加一笔钱，也不是链上退款 |
| 确认扣款 | 提现成功后，将此前的预扣记为已完成扣款 |
| 冲正 | 充值失效后撤销原来的入账，保留原记录和调整记录 |
“幂等”指同一笔业务被重复提交、查询或通知时，不会重复改账。充值用 txRef 关联一笔业务，提现用 withdrawOrderId，通知另用 eventId 识别重复事件。
推荐接入顺序
- 准备环境材料，确认开放链、资产和两组凭据。
- 最小接入路径，按充值、提现、通知和对账的主线完成闭环。
- 在 OG 后端建立玩家登录授权、持久账本和原订单记录，再实现通知端点，完成验签、事务幂等和回签。
- 按充值与提现接入取址、新提现、两类历史和单笔补偿；通过你们自己的 SSE 或短轮询更新手机原记录，再完成对接清单。
充值与提现各自独立接入并接收 Webhook。独立接入提现只需准备玩家主体和可用业务余额，不要求先发生充值。预期手机能连续提交独立提现，历史中的原单继续更新；任何一步结果不符，先核对该环境的请求、响应和 OG 本地账本，不用下一步的成功代替前一步的验证。