API 参考 / 提现
提交提现申请
提交一笔提现申请，并取得固定保存的首次受理结果。
/v1/withdrawals接入方服务端 → 支付服务
当前提现由人工处理。playerId 必填，必须与已建立的玩家主体一致；可先通过获取充值地址完成准备。提交成功后继续等待查询或终态通知，不按受理响应确认扣款。
调用说明
调用时机
你的业务后端已完成余额检查和预扣，且玩家已在支付服务建立主体后调用。
调用步骤
- 生成唯一的 30 位数字订单号，在本地保存订单、预扣金额和请求正文。
- 按环境资产精度换算最小单位金额，携带必填 playerId 提交签名请求。
- 核对 accepted=true、原订单号、链、合约、金额和收款地址，持久保存受理结果后，才通知手机清空表单并开始下一笔独立申请。用原订单号跟踪已经受理的记录。
结果处理
200 的合法受理响应不表示提现成功。响应固定为 manual_pending、manual、accepted=true、broadcast=false，且不含交易哈希。同一订单号和相同业务内容重复提交，仍返回这份首次响应；最新状态应通过玩家提现列表或单笔查询读取。重复受理快照不能覆盖后续终态。下一笔独立申请使用新的订单号，并按扣除全部已有预扣后的可用余额校验；当前提现需要人工处理，不由本接口自动转币。
用户每日提现上限
平台可为每条链配置一个适用于所有用户的 USDT 上限，每个 playerId 独立累计，同一用户在该链的所有收款地址共用额度，不与其他链合并。北京时间每天 00:00 重置，按钱包服务端记录申请时间所属日统计，不按手机点击、OG 建单或签名时间；昨日未完成订单不占今天额度。首次配置后只累计新申请，再次修改金额不清零已计入金额；清空后不限额，清空后重新保存才重新起算。
当前普通通道超限仍返回 422 和 {"error":"rejected"}，具体原因与重置时间通过 withdrawal_rejected Webhook 提供。已持久确定的拒单不创建可付款订单，也不会因跨日、提额或清空上限重新打开。不要新增请求字段或自行上传额度。
失败与重试
401 检查签名。泛化 422 可能是参数错误、玩家未准备好、订单内容冲突或每日上限拒绝，不能单凭它释放预扣。并非每个 422 都有通知：参数或链等预校验失败不会生成拒绝 Webhook，须先核实原请求。当前上限以已验签的完整 WithdrawalRejection 通知为明确拒绝证据；严格校验并绑定原请求和可信环境/接入方后，专用事务释放一次。只有原单采用平台另外开放的额度 v2 通道时，POST 422 才可能返回完整拒绝包络；该类已保存原单在能力暂停后仍保留原回应，不能由 schemaVersion=2 推断新单通道已启用。
超时、断连或 5xx 时保留原单和预扣，按原订单查询或同内容重试；当前普通通道保存了完整每日上限拒绝回执时，原单 GET 返回 200 和与 Webhook 相同的原文，可补查漏通知；旧泛化拒单或损坏回执仍为 503。未知结果不能换号重提；已明确拒绝后，玩家可在条件恢复时主动发起新的申请。
请求头
| 请求头 | 说明 |
|---|---|
X-Access-Key必填 | 平台发放的 API Access Key，用于识别你的业务后端。每个请求发送一次；只在服务端保存。 |
X-Timestamp必填 | 本次请求的 Unix 秒，使用十进制字符串。与服务端时间相差不得超过 300 秒；每个请求发送一次，重试重新生成。 |
X-Signature必填 | 本次 API 请求的 HMAC-SHA256 签名，64 个小写十六进制字符。使用 API 密钥签 METHOD|PATH|TIMESTAMP|QUERY|BODY，保留实际路径、query 和 body 字节；每个请求发送一次。 |
请求正文
提现所属玩家，当前服务必填，且必须已在支付服务建立主体。非空，最多 128 个 Unicode 字符，不含空白或控制字符。重试不得更换；建议与取址使用同一个简短 ASCII 标识。
1；最多字符数：128；除长度外，服务端还拒绝 Unicode 空白和控制字符；客户端不能只检查 maxLength。你的业务后端生成的提现订单号，恰好 30 位数字，必须作为字符串传输以保留前导零。提交、重试、查询和账务去重使用同一个值。
^[0-9]{30}$平台提供的链 ID。推荐传十进制数字字符串以避免精度丢失，也接受 JSON 整数。原始数字最多 20 位，去前导零后必须大于 0，并匹配已登记链。禁止负数、小数和科学计数；响应使用规范化后的数字字符串。
查看结构与约束
正文须符合以下一种结构。
string
string 格式规则：^0*[1-9][0-9]*$；最少字符数：1；最多字符数：20
integer
integer 最小值：1；最大值：99999999999999999999
代币最小单位的正整数字符串。按当前环境的资产精度换算，使用整数或高精度十进制计算，禁止浮点。例：若 USDT 精度为 6，1 USDT 填 "1000000"。提交提现不允许 0、前导零、小数或科学计数，数值不得超过 uint256。充值入账前先核对链和合约，不能把其他代币按 USDT 精度换算。
^[1-9][0-9]{0,77}$；字符串表示的数值上限：115792089237316195423570985008687907853269984665640564039457584007913129639935；pattern 只检查十进制写法与位数；还需用高精度整数比较数值上限，不能使用浮点比较。提现收款地址，必须与所选链类型一致，不能是全零地址。EVM 接受 0x/0X 加 40 位十六进制并转为小写；TRON 接受 34 位 Base58Check，或 41 开头的 21 字节十六进制（可带 0x/0X），统一转为 Base58Check。不要把 TRON 地址转为小写。
1不接受未定义字段。
响应字段
200 成功响应
返回首次受理结果。保留预扣，等待查询或通知给出最终状态；重复提交不会把本响应更新为当前状态。
accepted | true |
|---|---|
broadcast | false |
status | manual_pending首次受理成功提交响应固定值保留预扣，查询当前状态；重复提交仍返回此值。 |
route | manual人工提现提交响应固定值保存受理响应，等待人工提现结果。 |
你的业务后端生成的提现订单号，恰好 30 位数字，必须作为字符串传输以保留前导零。提交、重试、查询和账务去重使用同一个值。
^[0-9]{30}$固定为 true，表示订单已受理，不等于提现成功。
true固定为 false，仅描述首次受理响应。重复提交仍返回此值，不能据此判断订单当前是否已广播。
false固定为 manual_pending。保持预扣，使用查询或终态通知获取最终结果。
manual_pending平台返回的链名称，用于保存和展示。取址和提交提现时只传 chainId，不自行填写此字段。
1本条记录所属链的数字字符串。与当前环境约定的链核对，并与记录一起保存。
1该环境登记的 USDT 合约。取址和提现响应由平台返回，请与链一起保存；请求不填写此字段。EVM 合约使用小写十六进制，TRON 使用区分大小写的 Base58Check。是否开放某条链，以平台提供的环境信息为准。
1提现收款地址，必须与所选链类型一致，不能是全零地址。EVM 接受 0x/0X 加 40 位十六进制并转为小写；TRON 接受 34 位 Base58Check，或 41 开头的 21 字节十六进制（可带 0x/0X），统一转为 Base58Check。不要把 TRON 地址转为小写。
1代币最小单位的正整数字符串。按当前环境的资产精度换算，使用整数或高精度十进制计算，禁止浮点。例：若 USDT 精度为 6，1 USDT 填 "1000000"。提交提现不允许 0、前导零、小数或科学计数，数值不得超过 uint256。充值入账前先核对链和合约，不能把其他代币按 USDT 精度换算。
^[1-9][0-9]{0,77}$；字符串表示的数值上限：115792089237316195423570985008687907853269984665640564039457584007913129639935；pattern 只检查十进制写法与位数；还需用高精度整数比较数值上限，不能使用浮点比较。首次受理时间，Unix 秒整数。重复提交时保持不变；不是链上提现完成时间。
0固定为 manual，表示人工提现。重复提交不会更新此字段。
manual不接受未定义字段。
HTTP 状态码
| 状态码 | 含义与处理 |
|---|---|
200 | 返回首次受理结果。保留预扣，等待查询或通知给出最终状态；重复提交不会把本响应更新为当前状态。 |
401 | 请求未通过验签。先核对 Access Key、Unix 秒、路径/query 和原始 body，再重新签名请求。取址和充值接口在正文读取失败或超过 1 MiB 时也返回此状态。提现提交、取消、玩家提现列表和通知配置的超限正文返回 422，不是 401。 |
422 | 当前普通通道每日上限超限仍返回泛化 error=rejected，不能据此释放预扣；具体原因在完整且已验签的 withdrawal_rejected 通知中。只有原单采用另行开放的额度 v2 通道时，POST 才可能返回完整 WithdrawalRejection，已保存原单在能力暂停后也保留该回应。完整拒绝严格绑定原单与可信环境/接入方后，专用事务一次 held→released；已有受理或付款证据、同 ID 异文、身份不符时保留原账并持久核查。旧拒单跨日或提额不重开，不发送 HTTP Retry-After。 |
503 | 暂时无法确定结果，或查询结果尚未就绪。保留预扣，使用原订单号查询或同内容重试。500、502、504、超时和断连也按未知结果处理，不换新订单号。 |
失败时先核对 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 路径。预期工具最终请求的地址与对应环境配置一致；不一致时先检查主机、路径及前缀的拼接。