查询玩家充值 · OG 开发者中心

GET/v1/players/{playerId}/deposits

接入方服务端 → 支付服务

服务端签名认证

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

调用说明

调用时机

玩家已获得地址，但尚不知道本次充值的 txRef 时调用。

调用步骤

使用取址时的同一个 playerId 和 chainId。
将 playerId 放入路径，只传一个 chainId query，发送空 body 的签名 GET 请求。
展示每笔充值的金额与状态，并保存 txRef，供后续查询和去重。

结果处理

返回 items，包括 pending、confirmed、invalidated 三种状态；没有记录时为 []。按服务首次发现的顺序从新到旧，最多 1000 条，无下一页，也不受 24 小时窗口限制。它是当前同步视图，不是完整永久历史；完整账本须由 OG 持久保存。手机可在同一网络内按精确整数 blockNumber、logIndex 倒序展示，但这不改变接口的首次发现顺序。

本接口不支持 page、pageSize、cursor、时间或地址筛选。响应未提供精确链上时间或每笔充值收款地址，不能用 Webhook 接收时间、读取时间或当前充值地址填充历史事实。入账前仍须核对合约，并与通知、单笔查询共用 txRef 去重。

失败与重试

401 检查签名与实际 query 字节。422 检查 playerId、chainId，以及多余或重复 query、非空 body。200 空列表不表示充值失败；先核对玩家与链，等待同步后再查。网络异常后可重新查询。

请求头

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

路径参数

playerIdstring必填

取址时使用的同一个玩家标识，作为一个完整路径段传入。非空，不含空白、控制字符或 /；把 / 编成 %2F 也不支持。

格式规则：^[^/]+$；最少字符数：1

查询参数

chainIdstring必填

平台提供的链 ID，以十进制数字字符串传入。最多 20 位，去掉前导零后必须匹配开放链。

格式规则：^0*[1-9][0-9]*$；最少字符数：1；最多字符数：20

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

响应字段

200 成功响应

返回该玩家该链的当前已同步充值及状态。无匹配时返回 items: []，不返回 404。

application/json

`items[].status`3 个取值
含义与取值	适用范围与处理
待确认`pending`	充值查询展示处理中，继续查询，不入账。
已确认`confirmed`	充值查询 / 充值确认通知核对玩家、链与合约后按 txRef 入账；已失效或已冲正时，先按恢复规则单笔复核。
已失效`invalidated`	充值查询已入账则按原 txRef 冲正；未入账不改余额。不会单独发通知。

itemsarray<object>必返

按首次发现的顺序从新到旧，最多 1000 条，无下一页，也不按 24 小时截断。同一 txRef 只出现一次。

最多项数：1000

查看每项字段

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

statusstring必返

充值查询状态。confirmed 表示曾达到确认要求且尚未失效；仍在有效链上时，确认数回落不会自动变为 pending。失效及恢复均沿用原 txRef。按下表处理，入账前核对约定链与合约。

取值：pending、confirmed、invalidated

confirmationsinteger按条件返回

钱包最近一次同步实际返回的确认数，0 是已知值。缺字段表示未提供有效计数，不代表 0；不能只凭此数入账。

最小值：0

confirmationsRequiredinteger按条件返回

钱包最近一次同步实际返回的确认阈值。缺字段表示未提供有效阈值，不使用本地默认值补齐；按 status 判断当前充值状态。

最小值：1

blockNumberstring必返

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

txRefstring必返

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

最少字符数：1

不接受未定义字段。

HTTP 状态码

状态码	含义与处理
`200`	返回该玩家该链的当前已同步充值及状态。无匹配时返回 items: []，不返回 404。
`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 路径。预期工具最终请求的地址与对应环境配置一致；不一致时先检查主机、路径及前缀的拼接。