查询充值对账列表 · OG 开发者中心

GET/v1/deposits

接入方服务端 → 支付服务

高级对账接口，默认导航已收起

接口继续兼容，已有调用与旧文档链接可继续使用。请按下方范围与限制处理查询结果。

服务端签名认证

每次请求按方法、路径、时间戳、原始 query 与原始正文计算 HMAC。先完成身份验证和环境配置。

调用说明

此接口仅从默认文档导航收起；路径、签名、响应和下载规范保留，不是接口停用或弃用通知。手机主流程使用玩家充值列表和单笔查询。

调用时机

定期补查可能遗漏的充值，或核对本地已入账记录时调用。

调用步骤

发送签名 GET 请求，不传 query 或 body。
逐条核对玩家、chainId、tokenContract，并与本地 txRef 记录比对。
对遗漏记录按同一个 txRef 幂等入账；需要确认当前状态时调用单笔查询。

结果处理

返回 items，列表项不含 status，没有记录时为 []。不分页，不承诺排序。24 小时按服务记录的确认时间计算。结果只覆盖当前已同步记录，不是完整链上历史；一笔记录从列表消失，不代表它已失效，不能直接冲正。仅同步登记链名、链 ID 与代币合约匹配的记录，错误资产可能不可见；入账前仍须逐笔核对登记链和合约，缺记录时先检查转账资产与同步覆盖。

失败与重试

401 检查签名；422 检查是否误带 query 或 body。列表为空或与预期不符时，先核对环境和链，再按 txRef 单笔复核；仍有差异时请平台检查同步状态。网络异常后可重新查询。

请求头

请求头	说明
`X-Access-Key`必填	平台发放的 API Access Key，用于识别你的业务后端。每个请求发送一次；只在服务端保存。
`X-Timestamp`必填	本次请求的 Unix 秒，使用十进制字符串。与服务端时间相差不得超过 300 秒；每个请求发送一次，重试重新生成。
`X-Signature`必填	本次 API 请求的 HMAC-SHA256 签名，64 个小写十六进制字符。使用 API 密钥签 METHOD\|PATH\|TIMESTAMP\|QUERY\|BODY，保留实际路径、query 和 body 字节；每个请求发送一次。

GET 请求的 body 必须为空；只发送本页列出的路径和 query 参数。

响应字段

200 成功响应

返回当前对账窗口中的已确认充值。空 items 表示当前窗口没有匹配记录，不是同步健康证明。

application/json

itemsarray<object>必返

当前 24 小时对账窗口中仍已确认的充值，无排序保证。为空或记录消失时，不能直接判断充值失效。

查看每项字段

playerIdstring必返

你们业务系统中的稳定玩家标识，与获取充值地址时保持一致。非空且不含空白或控制字符；建议使用简短 ASCII 标识，并避免 /，便于跨接口使用。

最少字符数：1

chainNamestring必返

平台返回的链名称，用于保存和展示。取址和提交提现时只传 chainId，不自行填写此字段。

最少字符数：1

chainIdstring必返

本条记录所属链的数字字符串。与当前环境约定的链核对，并与记录一起保存。

最少字符数：1

txHashstring必返

充值交易哈希。EVM 为小写 0x 加 64 个十六进制字符；TRON 为不带前缀的 64 个小写十六进制字符。用于查看交易，不单独作为充值去重键；同一交易可能有多笔充值。

格式规则：^(0x)?[0-9a-f]{64}$

logIndexstring必返

这笔转入在交易中的日志序号，以无前导零的十进制字符串返回，允许 0，范围 0–18446744073709551615，最多 20 位。与交易哈希一起区分同一交易中的不同充值；排序或比较须使用大整数。

格式规则：^(0|[1-9][0-9]{0,19})$；最少字符数：1；最多字符数：20；字符串表示的数值下限：0；字符串表示的数值上限：18446744073709551615；pattern 只校验规范十进制写法与位数；自定义整数上下界不是标准 JSON Schema 校验，须用大整数精确比较，不使用浮点。

tokenContractstring必返

这笔已同步充值的代币合约。仅接纳登记链名、链 ID 与代币合约匹配的记录；错误资产可能不会出现。入账前仍须逐笔核对 chainId 和本字段，再按登记资产精度换算；缺记录时先检查转账网络、合约和同步覆盖。

最少字符数：1

amountstring必返

充值记录中的代币最小单位正整数字符串，范围 1 到 uint256 最大值（2^256-1）。先核对链与合约，再按环境资产精度换算；使用任意精度整数或十进制库，不用浮点。例：USDT 精度为 6 时，1000000 表示 1 USDT。

格式规则：

^(?:[1-9][0-9]{0,76}|10[0-9]{76}|11[0-4][0-9]{75}|115[0-6][0-9]{74}|1157[0-8][0-9]{73}|11579[0-1][0-9]{72}|1157920[0-7][0-9]{70}|11579208[0-8][0-9]{69}|115792089[0-1][0-9]{68}|1157920892[0-2][0-9]{67}|11579208923[0-6][0-9]{66}|115792089237[0-2][0-9]{65}|11579208923730[0-9]{64}|11579208923731[0-5][0-9]{63}|1157920892373160[0-9]{62}|1157920892373161[0-8][0-9]{61}|11579208923731619[0-4][0-9]{60}|115792089237316195[0-3][0-9]{59}|1157920892373161954[0-1][0-9]{58}|11579208923731619542[0-2][0-9]{57}|115792089237316195423[0-4][0-9]{56}|1157920892373161954235[0-6][0-9]{55}|115792089237316195423570[0-8][0-9]{53}|1157920892373161954235709[0-7][0-9]{52}|11579208923731619542357098[0-4][0-9]{51}|11579208923731619542357098500[0-7][0-9]{48}|115792089237316195423570985008[0-5][0-9]{47}|1157920892373161954235709850086[0-7][0-9]{46}|11579208923731619542357098500868[0-6][0-9]{45}|115792089237316195423570985008687[0-8][0-9]{44}|11579208923731619542357098500868790[0-6][0-9]{42}|115792089237316195423570985008687907[0-7][0-9]{41}|1157920892373161954235709850086879078[0-4][0-9]{40}|11579208923731619542357098500868790785[0-2][0-9]{39}|115792089237316195423570985008687907853[0-1][0-9]{38}|1157920892373161954235709850086879078532[0-5][0-9]{37}|11579208923731619542357098500868790785326[0-8][0-9]{36}|115792089237316195423570985008687907853269[0-8][0-9]{35}|1157920892373161954235709850086879078532699[0-7][0-9]{34}|11579208923731619542357098500868790785326998[0-3][0-9]{33}|115792089237316195423570985008687907853269984[0-5][0-9]{32}|1157920892373161954235709850086879078532699846[0-5][0-9]{31}|11579208923731619542357098500868790785326998466[0-4][0-9]{30}|115792089237316195423570985008687907853269984665[0-5][0-9]{29}|1157920892373161954235709850086879078532699846656[0-3][0-9]{28}|115792089237316195423570985008687907853269984665640[0-4][0-9]{26}|1157920892373161954235709850086879078532699846656405[0-5][0-9]{25}|11579208923731619542357098500868790785326998466564056[0-3][0-9]{24}|1157920892373161954235709850086879078532699846656405640[0-2][0-9]{22}|11579208923731619542357098500868790785326998466564056403[0-8][0-9]{21}|115792089237316195423570985008687907853269984665640564039[0-3][0-9]{20}|1157920892373161954235709850086879078532699846656405640394[0-4][0-9]{19}|11579208923731619542357098500868790785326998466564056403945[0-6][0-9]{18}|115792089237316195423570985008687907853269984665640564039457[0-4][0-9]{17}|1157920892373161954235709850086879078532699846656405640394575[0-7][0-9]{16}|11579208923731619542357098500868790785326998466564056403945758[0-3][0-9]{15}|11579208923731619542357098500868790785326998466564056403945758400[0-6][0-9]{12}|115792089237316195423570985008687907853269984665640564039457584007[0-8][0-9]{11}|11579208923731619542357098500868790785326998466564056403945758400790[0-9]{10}|11579208923731619542357098500868790785326998466564056403945758400791[0-2][0-9]{9}|1157920892373161954235709850086879078532699846656405640394575840079130[0-9]{8}|1157920892373161954235709850086879078532699846656405640394575840079131[0-1][0-9]{7}|11579208923731619542357098500868790785326998466564056403945758400791312[0-8][0-9]{6}|115792089237316195423570985008687907853269984665640564039457584007913129[0-5][0-9]{5}|1157920892373161954235709850086879078532699846656405640394575840079131296[0-2][0-9]{4}|11579208923731619542357098500868790785326998466564056403945758400791312963[0-8][0-9]{3}|115792089237316195423570985008687907853269984665640564039457584007913129639[0-8][0-9]{2}|1157920892373161954235709850086879078532699846656405640394575840079131296399[0-2][0-9]{1}|11579208923731619542357098500868790785326998466564056403945758400791312963993[0-4]|115792089237316195423570985008687907853269984665640564039457584007913129639935)$

；最多字符数：78；字符串表示的数值下限：1；字符串表示的数值上限：115792089237316195423570985008687907853269984665640564039457584007913129639935

blockNumberstring必返

首次观察到充值所在的区块高度，后续保留首次值，仅供展示，不作为充值去重键或重组后的最新位置。使用无前导零的十进制字符串，允许 0，范围 0–18446744073709551615，最多 20 位；排序或比较须使用大整数。

txRefstring必返

支付服务返回的充值唯一标识，直接保存，不自行计算。入账、查询、冲正和恢复都使用它。同一交易不同 logIndex 是不同充值，不能仅按 txHash 去重。

最少字符数：1

不接受未定义字段。

HTTP 状态码

状态码	含义与处理
`200`	返回当前对账窗口中的已确认充值。空 items 表示当前窗口没有匹配记录，不是同步健康证明。
`401`	请求未通过验签。先核对 Access Key、Unix 秒、路径/query 和原始 body，再重新签名请求。取址和充值接口在正文读取失败或超过 1 MiB 时也返回此状态。提现提交、取消、玩家提现列表和通知配置的超限正文返回 422，不是 401。
`422`	查询格式不正确。检查路径参数，仅保留接口允许的 query，并保证 GET body 为空；修正后可重新查询。

失败时先核对 HTTP 状态、原始签名内容和环境配置，见错误处理。

接口规范与环境配置

规范包含当前主动接口、每日提现上限查询和一个通知接收操作。高级 24 小时充值对账接口仅收起展示，旧直链和下载规范保留；每日上限查询读取与后台相同的当前规则；仍须核对本环境服务版本与数据库依赖。字段、必填项、枚举和示例见各接口；机器可读版本为 OpenAPI 3.0 规范。

操作	方法与路径	用途
createDepositAddress	`POST /v1/addresses`	获取玩家充值地址
listPlayerDeposits	`GET /v1/players/{playerId}/deposits?chainId=...`	充值页查进度
queryDeposit	`GET /v1/deposits/{txRef}`	复核单笔充值
submitWithdrawal	`POST /v1/withdrawals`	提交提现申请
listPlayerWithdrawals	`GET /v1/players/{playerId}/withdrawals?chainId=...&page=1&pageSize=20`	分页补查玩家该链已受理提现
queryWithdrawal	`GET /v1/withdrawals/{withdrawOrderId}`	查询提现最新状态
cancelWithdrawal	`POST /v1/withdrawals/{withdrawOrderId}/cancel`	取消尚未进入链上处理的提现，成功后为 `refunded`
queryWithdrawalQuota	`GET /v1/withdrawal-quota?playerId=...&chainId=...`	读取与后台相同的当前每日上限和当日申请额；quota:null 表示不限额
getWebhookConfig	`GET /v1/webhook-config`	只读核对通知 URL、启用状态、凭据是否配置、可用性及配置版本；不代表已送达
receiveTerminalNotice	`POST {notifyUrl}`	你的端点接收交易通知

导入 API 工具后，将 servers[0].variables.baseUrl.default 设为平台发放的 API 接入地址；每次调用都重新签名。通知操作独立使用你的完整通知 URL：notifyOrigin 只填协议、主机和端口，操作路径填写接收端的实际路径。默认 /notify 只是示意，不要在已有路径后再次追加，也不能把它当作业务 API 路径。预期工具最终请求的地址与对应环境配置一致；不一致时先检查主机、路径及前缀的拼接。