获取充值地址 · OG 开发者中心

POST/v1/addresses

接入方服务端 → 支付服务

服务端签名认证

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

调用说明

调用时机

玩家打开充值页、需要展示该链收款地址时调用。

调用步骤

使用业务系统中稳定的玩家标识，并选择平台发放的 chainId。
签名后提交请求，将成功响应中的地址、链和合约一起保存。
在充值页展示链名、USDT 合约和地址，再由地址生成二维码。

结果处理

同一玩家、同一条链、同一 USDT 合约，在收款合约未更换时，重复取址会返回相同地址。平台更换该链的 USDT 合约或收款合约后可能返回新地址，应以最新成功响应更新地址簿。地址按原样保存，不要强制转为小写。

失败与重试

401 先检查签名。422 先检查字段和 chainId；参数正确仍失败时，联系平台核对该链的取址配置。未成功取址前，不展示示例地址。可使用同一玩家和链重试。

请求头

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

请求正文

application/json · 字段类型和约束如下

playerIdstring必填

获取充值地址的玩家标识。非空，不含空白或控制字符；UTF-8 编码最多 128 字节，中文按字节计算。为兼容玩家查询，请避免 /；建议使用稳定的 ASCII 标识。

最少字符数：1；最多字符数：128；UTF-8 最多字节数：128；OpenAPI 的 maxLength 按字符计数；服务端另检查 UTF-8 字节数，二者不能互相代替。

chainIdstring | integer必填

平台提供的链 ID。推荐传十进制数字字符串以避免精度丢失，也接受 JSON 整数。原始数字最多 20 位，去前导零后必须大于 0，并匹配已登记链。禁止负数、小数和科学计数；响应使用规范化后的数字字符串。

查看结构与约束

正文须符合以下一种结构。

string

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

integer

integer 最小值：1；最大值：99999999999999999999

不接受未定义字段。

响应字段

200 成功响应

返回可保存和展示的充值地址，以及对应链和 USDT 合约。请提醒玩家选择相同网络及资产。

application/json

addressstring必返

玩家在该链的充值地址。保存并使用返回的原文；EVM 地址可能含校验和大写字母，不要强制改成小写。

最少字符数：1

chainNamestring必返

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

最少字符数：1

chainIdstring必返

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

最少字符数：1

tokenContractstring必返

该环境登记的 USDT 合约。取址和提现响应由平台返回，请与链一起保存；请求不填写此字段。EVM 合约使用小写十六进制，TRON 使用区分大小写的 Base58Check。是否开放某条链，以平台提供的环境信息为准。

最少字符数：1

不接受未定义字段。

HTTP 状态码

状态码	含义与处理
`200`	返回可保存和展示的充值地址，以及对应链和 USDT 合约。请提醒玩家选择相同网络及资产。
`401`	请求未通过验签。先核对 Access Key、Unix 秒、路径/query 和原始 body，再重新签名请求。取址和充值接口在正文读取失败或超过 1 MiB 时也返回此状态。提现提交、取消、玩家提现列表和通知配置的超限正文返回 422，不是 401。
`422`	无法提供充值地址。先检查 playerId、chainId 和多余字段；参数正确仍失败时，请平台检查该链配置和取址服务。仅凭 422 不能断定是参数错误。

失败时先核对 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 路径。预期工具最终请求的地址与对应环境配置一致；不一致时先检查主机、路径及前缀的拼接。