金额、链和地址 · OG 开发者中心

字段规则

字段	规则
`amount`	基础单位的十进制整数字符串，不使用浮点。按环境提供的资产精度换算；例如精度为 6 时，`1 USDT = "1000000"`。提现金额必须大于 0、无前导零，最多 78 位且不超过 256 位无符号整数上限；不接受小数或科学计数
`chainId`	使用环境发放的数字字符串。取址和提交提现也接受 JSON 整数，原始数字最多 20 位，不接受小数或科学计数；前导零会规范化。响应始终是数字字符串。推荐一直用字符串避免精度丢失
`chainName`、`tokenContract`	取址与提现请求不传，平台按登记的 `chainId` 填入响应。充值记录中的合约来自观察结果，入账前必须与登记资产比对
`playerId`	业务系统的玩家标识，非空，无空白或控制字符。取址最多 128 个 UTF-8 字节；提现最多 128 个 Unicode 字符。跨接口使用时不要含 `/`，编码为 `%2F` 也不能用于玩家查询
`withdrawOrderId`	你的提现订单号，恰好 30 位数字的字符串，保留前导零；同一笔提现始终使用同一订单号
`txRef`	平台返回的充值唯一标识，完整保存；同一交易的不同日志可能有不同 `txRef`。不要自己用交易哈希替代
`address`	取址返回值，原样保存和展示；EVM 地址可能采用校验和大小写
`toAddress`	提现收款地址。EVM 接受 `0x`/`0X` 加 40 个十六进制字符并转为小写；TRON 接受 Base58Check 或 `41` 加 40 个十六进制字符（可带 `0x`/`0X`），转为 Base58Check。全零地址拒绝；格式可识别不代表环境已开放该链
`txHash`	交易哈希，不能单凭它确认到账。EVM 充值输出小写 `0x` 加 64 个十六进制字符；TRON 充值输出不带前缀的 64 个小写十六进制字符。提现查询与终态允许不带 `0x` 的 64 个小写十六进制字符，进度可能直接带上游文本。不要按前缀判断链
`logIndex`、`blockNumber`	规范十进制字符串，只允许 `0` 或不带前导零的正整数，最多 20 位，范围 `0`–`18446744073709551615`。分别表示交易日志序号和首次观察的区块高度；高度后续保持首次值，仅供展示，不作为充值去重标识。比较或排序使用大整数，不能用浮点
`confirmations`、`confirmationsRequired`	玩家充值列表及单笔查询中的可选整数，分别来自钱包最近同步的确认数和阈值；两者独立可选。确认数 `0` 是已知值，缺字段表示未知，不补成 `0` 或默认 `12`；账务仍以 `status` 为准
`eventId`	不透明的通知事件标识，完整保存，允许包含冒号；同一事件重试不变。事件类型看 `type`，不解析 ID 猜测

充值查询状态

用于单笔查询和玩家充值列表。近 24 小时对账列表的项目没有 status，只包含仍为 confirmed 的记录。

页面应同时读取状态和可选确认数：计数完整时显示例如 3/12；confirmed 且计数缺失时仍显示已确认，提示计数尚未提供，不显示等待确认。若预期计数未返回，先请平台核对充值同步是否已经带上确认数，再检查本查询响应里的 confirmations 与 confirmationsRequired。中间进度回调可能错过；充值成功通知不携带计数，可用查询补齐。

`status`	中文含义	账务动作
`pending`	已发现，尚未确认有效	不入账、不冲正，继续查询
`confirmed`	曾达到确认要求，且未被判定失效；确认数回落不一定改变此状态	核对玩家、链与合约后，按 `txRef` 入账一次；已失效或已冲正的恢复须当前单笔查询确认
`invalidated`	该充值当前已失效	未入账则保持不入账；已入账则冲正一次。没有单独的失效通知

提现查询状态

提交成功的响应固定保存为 manual_pending，查询接口才返回最新状态。普通人工提现和取消后的 refunded 属于当前流程；voucher_checking、voucher_failed 只在已配置凭证核验时出现；auto_sending 是兼容状态，未启用自动提现时不会出现。仅登记网络不代表凭证核验或自动提现已启用。

`status`	中文含义	范围	账务动作
`manual_pending`	人工提现处理中，可能处于审批、等待链上观察或确认阶段	当前流程	保持预扣。它不等于“尚未广播”
`held`	需要人工复核，暂挂起	当前流程	保持预扣，等待处理
`succeeded`	已确认提现成功	当前流程	确认扣款一次
`failed`	订单已失败终结	当前流程	释放原预扣一次；不同于提交 HTTP 422
`auto_sending`	自动提现处理中	兼容	保持预扣
`voucher_checking`	提现凭证校验中	已配置凭证流程	保持预扣
`voucher_failed`	提现凭证校验未通过，订单尚未终结	已配置凭证流程	保持预扣，不能当作终态
`refunded`	取消尚未广播的提现后，订单以已退款终结	当前流程	释放预扣一次；不表示链上向玩家地址转回 USDT

route 只有 manual（人工提现）和 auto（自动提现，兼容值），不决定账务动作。broadcast 是响应中的广播标记：提交响应固定为 false，查询按可用的交易哈希设置；`false` 不能证明链上尚未广播。有哈希或 true 也不能代替 succeeded。

已配置凭证流程的查询还可能返回 verificationStage、voucherTxHash、payerAddress、failureCode、confirmations 与 requiredConfirmations。只使用实际返回的字段：确认数 0 是已知值，缺失表示未知；requiredConfirmations 是提现字段名，与充值的 confirmationsRequired 不同。不要把旧尝试的计数补到新快照上。

`verificationStage`	含义	接收端处理
`awaiting_proof`	等待录入交易哈希	展示等待状态，保持预扣
`verifying` / `confirming`	核验提现凭证 / 等待区块确认	展示进度，保持预扣
`proof_failed`	本次凭证未通过	保存 `failureCode`，等待平台核查或更正凭证，保持预扣
`succeeded`	本次提现凭证核验成功	仍按订单 `status=succeeded` 幂等确认扣款

预期页面可以解释当前提现阶段，而不会将凭证未通过当作提现失败终态。缺少预期的凭证字段时，先查询原订单并核对平台是否启用、同步了对应的核验流程；OG 不自行发起平台审批或录入凭证。

通知的 phase 仅有 progress，表示进度。充值成功和提现终态不带 phase，不存在 phase: terminal。完整的 type/status/phase 对应关系见事件类型，不能把查询状态直接套到通知上。